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1. Introduction 


This book will help you quickly get up to speed and build mainstream 
desktop graphical user interfaces with Python 3 and Tkinter. As you 
may know, Tkinter is the Python interface to a GUI library called Tk. 
It was initially developed for the Tcl language but widely adopted by 
other dynamic languages, including Ruby, Perl, and of course, 
Python. 

This book will teach you what you need to know about Tkinter and 
Tk and, in particular, Tk 8.5 and 8.6. Tk 8.5 was a milestone release. 
It marked a significant departure from older versions of Tk that most 
people know and feve recognize. 

The downside is that unless you know one or two crucial things, 
it's actually not that significant a release. In fact, it will seem like 
nothing changed at all. Due to backward compatibility, unless 
existing programs make a few simple changes, they won't look any 
different. (Imagine if you just moved into a rustic and quirky historical 
home. You'd want someone to point out where they've hidden the 
light switches and power outlets, wouldn't you?) 

If you're new to Tk or creating a new program, this book will 
ensure you get started the right way. If you've used Tk before, it will 
help you bring your knowledge right up to date. And if you're 
updating code that may have been written years ago, you'll see step- 
by-step how to bring it into the modern age. It's a cliche, but | can't 


believe how much I've learned in writing this book, and I've been 
using Tk for over twenty-five years. 

The general state of Tk documentation (outside the Tcl-oriented 
reference documentation, which is excellent) is unfortunately not at a 
high point these days. This is particularly true for developers using 
Tk from languages other than Tcl, and developers working on 
multiple platforms. So this book will, as much as possible, target 
developers on the three main platforms (Windows, macOS, and 
Linux). 

It's also not a reference guide. It's not going to cover everything, 
just the essentials you need in 95% of applications. The rest you can 
find in reference documentation. 


1.1. Who This Book Is For 


This book is designed for developers building tools and applications 
in Tk. It's also concerned with fairly mainstream graphical user 
interfaces, with buttons, lists, checkboxes, rich text editing, 2D 
graphics, etc. So if you're either looking to hack on Tk's internal C 
code or build the next great 3D immersive game interface, this is 
probably not the material for you. 

This book also doesn't teach you Python, so you should have a 
basic grasp on that already. This book uses Python 3 exclusively and 
does not cover using Tkinter in Python 2. Similarly, you should have 
a basic familiarity with desktop applications in general. While you 
don't have to be a user interface designer, some appreciation of GUI 
design is always helpful. 


1.2. Why Tkinter? 


If you're new to building desktop graphical user interfaces in Python, 
why might you use Tkinter? After all, there are many options, 
including PyQt, PySide, WxPython, PySimpleGUI, and Kivy. Each 
has various pluses and minuses. 

There are several reasons people chose Tkinter. It's Python's 
default GUI toolkit, the only one included in its standard library. It's 
cross-platform so that the same code can run across Windows, 
macOS, or Linux systems. Perhaps most importantly, it's easy to 
learn and work with. It keeps boilerplate and overhead to a minimum. 
It's Pythonic; it just feels right. Unlike many options which are front 
ends to C++ libraries, Tkinter is built on a user interface tool 
designed for dynamic languages. 

Many large commercial applications these days are web-based. In 
fact, web (and mobile) development sucked most of the life out of 
desktop user interface toolkits, which is why so many mature tools 
are still widely used today. Writing desktop applications still makes 
sense in many situations, whether open source projects, personal or 
company-internal tools, or putting together a quick front end for a 
specific project. These are situations where Tkinter excels. 


1.3. Modern Best Practices 


This book is all about building modern user interfaces using the 
current tools Tk has to offer. It's all about the best practices you need 
to know to do this. 

For most tools, you wouldn't think you'd have to say something 
like that. But for Tk, that's not the case. Tk has had a very long 
evolution, and any evolution tends to leave you with a bit of cruft. 
Couple that with how much graphical user interface platforms and 
standards have evolved in that time. You can see where keeping 
something as large and complex as a GUI library up to date (and 
backward compatible) may be challenging. 

Tk has, for most of its lifetime, gotten a bad rap, to put it mildly. 
Some of this has been well deserved, most of it not so much. Like 
any GUI tool, it can be used to create absolutely terrible looking and 
outdated user interfaces. Still, with the proper care and attention, it 
can also be used to develop spectacularly good ones. Most people 
know about the crappy ones; most of the good ones people don't 
even know are done in Tk. In this book, we're going to focus on what 
you need to build good user interfaces. Thankfully, this isn't nearly as 
hard as it used to be before Tk 8.5. 

So to sum up: modern desktop graphical user interfaces, using 
modern conventions and design sense, using the modern tools 
provided by Tk 8.5 and 8.6. 


Tk Extensions 


When it comes to modern best practices, Tk extensions deserve a 
special word of note. Over the years, developers have created all 
kinds of add-ons to Tk, for example, adding new widgets not 
available in the core (or at least not at the time). Some well-known 
and quite popular Tk extensions include BLT, Tix, iWidgets, 
BWidgets; there are many, many others. 

Many of these extensions were created decades ago. Because 
core Tk has always been highly backward compatible, these 


extensions generally continue to work with newer versions. However, 
they may not reflect current platform conventions or styles. While 
they "work", they can make your application appear extremely dated 
or out of place. In many cases, the facilities they provide have been 
obsoleted by newer and more modern facilities recently built into Tk 
itself. 

If you decide to use Tk extensions, it's highly recommended that 
you investigate and review your choices carefully. 


1.4. The Better Way Forward 


Tk gives you a lot of choices. There are at least six different ways to 
layout widgets on the screen. Multiple widgets can be used to 
accomplish the same thing, and that's before considering any Tk 
extensions. Tk emphasized backward compatibility, which is a 
double-edged sword. Most of these old ways of doing things still 
keep working, year after year. That doesn't necessarily mean you 
should still be using some of them. 

So there are many in Tk, but frankly, all that choice gets in the 
way. If you want to learn and use Tk, you don't need to know ten 
different ways to accomplish the same thing. You shouldn't need to 
do all the research, explore all the options, and make a choice 
yourself. You need to know the right way to do things today. That's 
what this book will give you. Think of it as the documentation 
equivalent of opinionated software. 

So we'll often use different ways of doing things than you'd find in 
other documentation or examples. Usually, it's because when those 
were written, the better ways didn't even exist yet. (Here's a litmus 
test for Tk documentation: does it use the archaic pack instead of the 
modern grid?) Later on, once you're an expert, and you're 
encountering some wacky situation where the typical choice doesn't 
fit, you can go hunt around for alternatives. 


1.5. How to Use 


While the book is designed to be used linearly, feel free to jump 
around as you see fit. We'll often provide links to go for more 
information, such as the full reference for a particular command. 
While Tk's native reference documentation is Tcl-based, it's 
extremely accurate and well written, and usually easy to "translate" 
into Python. Unfortunately, there's not yet Tkinter reference 
documentation that approaches its quality or completeness. 

You can find a GitHub repository containing many of the larger 
examples accessible via https://tkdocs.com/code/. You'll also find 
direct links below the code listings in the book. 


Conventions 


As is typically done, code listings, interpreter or shell commands and 
responses will be indicated with a fixed-width font. When showing 
an interactive session with the interpreter, the parts you enter will be 
IN bold fixed-width. 

When describing procedure or method calls, the literal parts (e.g., 
the method name) will be in a plain fixed-width font, parameters 
where you should fill in the actual value will add italics, and optional 
parameters will be surrounded by '?', e.g. set variable ?value?. 

In general, when referring to these procedures or method calls in 
the text, we'll omit punctuation (parentheses, commas, equals, etc.) 
that Tkinter requires. Code snippets show the full syntax, of course. 

You'll see some paragraphs that are separated from the main text. 
These are used for several different things. Each is identified with a 
different icon, as follows: 


Q This paragraph will help point out common mistakes that people make 
or suggest useful but not necessarily obvious solutions related to the 
topic. 


This indicates a new way of doing things in Tk 8.5 or Tk 8.6 that is very 

different from how things would have been done previously. People 
urcrane familiar with older versions of Tk, or working on programs developed 
= with older versions of Tk, should pay close attention. 


AXE. This paragraph provides some additional background information. It's 
not strictly necessary to learning the topic at hand, but that might help 
you understand a bit more about how or why things are done the way 

they are. 


@ This indicates an area in Tk that could most charitably be described as 

a "rough edge." It may indicate a bad or missing API requiring you to 

use a workaround in your code. Because these things tend to get fixed 

up over time, it's worth marking them in your code with a "TODO." That way, 

you can remember to go back later and see if a newer API resolves the 
problem cleanly. 


2. A Brief History of Tk and 
Tkinter 


Tk is a user interface toolkit that makes it easy to build desktop 
graphical user interfaces. Tk is cross-platform, meaning the same 
code can be made to run the same on Windows, macOS, or X11 
under a huge range of Unix systems (e.g., Linux). Compared with 
many user interface toolkits, Tk is also quite high-level, meaning that 
it takes care of many details for you. That makes your code simpler. 
You don't have to be a professional programmer to use it. It's ideal 
for when you want to quickly create a user interface, perhaps for a 
personal project or an internal company tool. 

Tk is also unique in that it was designed from the start to be 
paired with a high-level dynamic programming language (like Tcl, 
Python, Ruby, Perl) as opposed to lower-level languages like C or 
C++. In fact, you'll find a Tk binding for most dynamic languages 
available today. It's easy to embed and produces executables much 
smaller than many other GUI libraries. It also is BSD-licensed, 
making it attractive for both open source and commercial 
developers. 

Together, these factors make Tk an attractive option for people 
trying to develop a GUI on Windows, macOS, or Unix, especially if 
they want it to run on all three. And because Tk is used from 
dynamic programming languages, it's an accessible tool not only for 


hardcore developers but also for many people without a computer 
science or engineering background. 

Because it's been around forever and has changed a lot over the 
years, there's a ton of horribly outdated and incorrect information out 
there. This makes it pretty overwhelming if you just want to figure out 
if and how to use Tk today. That's what this book will help with. 

Before diving in, we'll provide a brief history of where it came 
from, why and how it caught on, and how things have evolved. This 
will help put a great many things in context. 


2.1. The Early Years 


Tk was created around 1988 by John Ousterhout, a computer 
science professor at UC Berkeley. It was developed as a way to 
easily build GUI's from his Tcl scripting language. Tcl was Unix-only 
at first, and so Tk ran under X11. The first open source release was 
around 1991, with rapid adoption starting about a year later. You can 
find John's recollections of the early years at the main Tcl/Tk 
developer site, www.tcl.tk. 

Tk caught on because lots of people at universities were using 
Unix/X11 in the early 1990s. The mainstream X11 libraries like Xt, 
Xaw and Motif were horribly painful to use. A "hello world" 
application would literally take a couple hundred lines of C or C++. 
Then Tk comes along, where a good looking "hello world" is a one- 
liner, and the toolkit took care of all the housekeeping like redrawing, 
clipping, hit detection, event dispatch, and more. It was a no-brainer. 

For a (very brief) moment, Tcl and Tk were the cool and exciting 
new things. Developers and users of languages other than Tcl paid 
attention too, and many language bindings to Tk were developed. 
Python's Tkinter first appeared around mid-1994. 


2.2. [Ihe Middle Years 


In 1994, John moved to Sun Labs, where he assembled a team to 
help move Tcl/Tk forward even more. The bulk of the team shifted to 
a Startup called Scriptics (later Ajuba) and continued to evolve Tcl/Tk 
until the company was acquired in 2000, mostly for the non-Tcl/Tk 
assets it had developed. 

For Tk, those years produced a major step forward, the 
development of the Windows and macOS versions. This meant that 
the same script to produce a GUI would run unmodified on Unix, 
Windows, or macOS. 

Stewardship of Tk (and Tcl) moved to a more community-centered 
model in mid-2000, with a Icl/Tk core team at the center, but with 
much broader participation. 

Tk continued to evolve, but the pace slowed. Incremental 
enhancements and adding support for new macOS and Windows 
versions precluded any major leaps forward. Almost no core work 
aimed to track the dueling Gnome/KDE user interface standards 
emerging on Linux. Though Tk has always’ been highly 
customizable, unless you knew what you were doing and put in the 
effort, it started looking more and more dated. 


2.3. The Silent Revolution 


Tk 8.5.0 was released on December 20, 2007, and was as crucial a 
step forward as the Windows and macOS versions in 8.0, over ten 
years earlier. The core distribution included "new" widgets for such 
now-common components like trees, combo-boxes, tabbed 
notebooks, and more. These had only been available before as add- 
ons (with far too many to choose from). 

Most importantly, Tk 8.5 added a new "themed" widget set, which 
complements but does not replace the "classic" widget set. The 
classic widgets provide full backward compatibility, retaining their 
almost infinite flexibility, but often dated appearance. The new 
themed widgets look much better on their respective platforms out of 
the box. It was intended that developers should use them for nearly 
all mainstream user interface needs. The new widgets also support 
changing their look and feel via themes, making "skinnable" user 
interfaces easy for applications and platforms where they are 
appropriate. 

Why do | call this Tk's "silent revolution?" This all happened about 
ten years past its heyday. At the time, web development had 
relegated desktop GUI's to irrelevancy, and few developers were 
paying attention to Tk. And if you weren't paying attention, you 
wouldn't know that anything changed. Thanks to backward 
compatibility, for most people, it really didn't. Sadly. 


2.4. Tk Today 


This is being written in September 2020. In the dozen years since 
8.5.0 was released, there have been approximately 30 new releases 
of the core Tcl/Tk package, which is currently at version 8.6.10. In 
that time, even though the development of new features has slowed, 
it's continued to improve. 


2.5. Tkinter 


Python's Tkinter was one of the earlier bindings to Tk, and certainly 
one of the most popular. Tkinter was originally written by Fredrik 
Lundh. Tkinter works like most Tk bindings by embedding a Tcl 
interpreter inside the Python application. Tkinter commands are then 
translated into Tcl commands and evaluated in that interpreter. 

In 2009, Guilherme Polo added support for the newer "ttk" themed 
widgets from Tk into Tkinter, starting with Python 2.7 (on the 2.x 
branch), and Python 3.1. This opened the door for building far better 
user interfaces with Tkinter. Documentation remained the main 
obstacle to Python programmers learning about the new themed. 


3. Installing Tkinter 


In this chapter, you'll get Tk and Tkinter installed on your machine, 
verify it works, and then see a quick example of what a Tkinter 
program looks like. 

In the past, this was a multiple-step process. However, if you're 
using Python 3.7 or newer, you're in luck! The Python binary 
installers for macOS and Windows, available at python.org, now 
include everything you need to use Tkinter out of the box, including 
the underlying Tcl/Tk libraries. 

If you're running on Linux, all popular distros have packages 
available that also make installing Tkinter a breeze. 

If you're using an older version of Python or compiling from 
source, you'll need to install Tcl/Tk on your system. If you're in this 
situation, we'll explain how to use a free distribution called ActiveTcl 
(made by ActiveState) to do so. 

Remember, this book assumes you're using Python 3, not 
Python 2. There are some significant differences between the two. 
That includes module naming, which is the first thing you'll encounter 
when trying to use Tkinter. In Python 2.x, the module was named 
Tkinter (note the uppercase "T"), while in Python 3.x it is named 
tkinter (all lowercase). 


3.1. Installing Tk on macOS 


The Easy Way 


As noted, the easiest way to get Tk and Tkinter installed on your 
system is using Python's binary installer, available at python.org. 
Thanks to work by Python core developer Ned Deily, binary installers 
starting with version 3.7 include Tcl and Tk. 


AXE. Remember, we're using Python 3.x here, not 2.x. As of this writing, the 
latest 3.9 installer (3.9.0rc1) includes Tk 8.6.8. 


If, however, you're compiling Python yourself, you'll have more work 
to do. Read on... 


Installing Tcl/Tk 


The Tkinter module is included with core Python, of course, but you'll 
need a version of Tcl/Tk on your system to compile it against. Do 
yourself a huge favor and get the most recent version. 

Whatever you do, do not rely on the Tk versions included in 
macOS! Older versions included Tk 8.4.x. Even more recent macOS 
versions include an early 8.5 version (8.5.9, released in 2010), which 
has several serious bugs that are easily triggered by Tkinter. 

While there are several different ways to get Tcl and Tk onto your 
machine, the easiest and most recommended is to use the Active Tcl 
distribution. 

In your web browser, visit www.activestate.com/products/activetcl. 
Download ActiveTcl (as of this writing, it's version 8.6.9). Make sure 
to download an 8.6.x version, not something older! Note that you will 
need to create an account with ActiveState (no cost) to download it. 
After it's downloaded, run the installer to get Tcl and Tk loaded onto 
your machine. 


AXE. If you're a masochist and want to read about other Tcl/Tk options and 
variations and how they interact with Python, see the Mac Tcl/Tk page 


at python.org/download/macacltk. If you want to compile Tcl/Tk from source, 
see www.tel.tk. 


Compiling Python 


When compiling Python from source, you may need to tell it where to 
find the ActiveTcl (or other) distribution. Otherwise, it might not find 
any Tcl/Tk distribution (so Tkinter won't work), or it could find the 
(ancient and broken) version of Tcl/Tk supplied with macOS. 

If you're using Python 3.9 or newer, the build system will look in 
/Library/ Frameworks, where ActiveState and other custom builds are 
typically installed. 


% ./configure 
make 


oe 


Q The initial "%" is the Unix shell prompt; you don't have to type it. The 
rest of it should all go on one line, without adding line breaks. 


When compiling Python versions prior to 3.9, you will need to add 
two new command-line options to the initial ./configure in the 
Python build process. The first provides the locations of the Tcl and 
Tk include files, and the second provides the locations of the Tcl and 
Tk libraries. These are usually found in two different locations (i.e., 
Tcl. framework and Tk. framework). You therefore need to provide two 
locations for the include files and two for the libraries. Note the 
location of the quotes in the command below and the spaces 
separating the Tcl and Tk paths. 


% ./configure --with-tcltk-includes="- 

I/ Library/ Frameworks/Tcl.framework/Headers - 

I/ Library/ Frameworks/Tk.framework/ Headers" --with-tcltk- 
libs="/ Library/ Frameworks/Tcl.framework/ Tcl 

/Library/ Frameworks/Tk.framework/ Tk" 


io) 


% make 


q\ If you have multiple versions of Tcl/Tk installed on your system (and in 
the same frameworks), you may need to check inside the framework to 


ensure the most recent version is marked as the current one. If not, you may 
need to adjust your paths to point to the specific version (i.e., versions/8 .x/) 
within each framework. 


When everything is built, be sure to test it out. Start Python from your 
terminal, e.g. 


3 ./python.exe 


This should give you the Python command prompt. From the prompt, 
enter these two commands: 


>>> import tkinter 
>>> tkinter. test() 


This should pop up a small window; the first line at the top of the 
window should say "This is Tcl/Tk version 8.6"; make sure it is not 
8.4 or 8.5! 


Get an error saying No module named tkinter? You're probably using 
Python 2. This book assumes Python 3. 


You can also get the exact version of Tcl/Tk that is being used with: 
>>> tkinter.Tcl().eval(' info patchlevel' ) 


It should return something like '8.6.9". 


AXE. Verified install using Active Tcl 8.6.9.8609.2 and Python 3.90rc1 source 
code from python.org on macOS 10.15.6. 


3.2. Installing Tk on Windows 


Tkinter (and, since Python 3.1, ttk, which is the interface to the 
newer themed widgets) is included in the Python standard library. 
We highly recommend installing Python using the standard binary 
distributions from python.org. These will automatically install Tcl/Tk, 
which of course, is needed by Tkinter. 

If you're instead building Python from source code, the Visual 
Studio projects included in the "PCbuild" directory can automatically 
fetch and compile Tcl/Tk on your system. 

Once you've installed or compiled Python, test it out to make sure 
Tkinter works. From the Python prompt, enter these two commands: 


>>> import tkinter 
>>> tkinter. test() 


This should pop up a small window; the first line at the top of the 
window should say "This is Tcl/Tk version 8.6"; make sure it is not 
8.4 or 8.5! 


Get an error saying No module named tkinter? You're probably using 
Python 2. This book assumes Python 3. 


You can also get the exact version of Tcl/Tk that is being used with: 
>>> tkinter.Tcl().eval(' info patchlevel' ) 


It should return something like '8.6.9'. 


AX. Verified using Python 3.9.0rc1 binary installer from python.org 
(containing Tcl/Tk 8.6.9) on Windows 10 version 1809. 


3.3. Installing Tk on Linux 


Tkinter (and, since Python 3.1, ttk, which is the interface to the 
newer themed widgets) is included in the Python standard library. It 
relies on Tcl/Tk being installed on your system. Depending on how 
you install Python, this may not happen automatically. 


AXE. Remember, we're using Python 3.x here, not 2.x. 


You have several different options to get Python and Tkinter 
onto your machine. We'll show you two, using your distro's package 
manager, or compiling from source. 


Option 1. Your Linux Distribution's Package Manager 


Currently supported Linux distributions usually install a recent 
version of Python 3.x by default. If not, they have a package (.deb, 
.fpm, etc.) that you can install using their package manager. This is 
usually the easiest way to install Python. 

However, after you're done installing Python, you should verify 
that Tkinter works correctly. Start up a Python shell (e.g. 
/usr/bin/python3) and verify the install (see below). 

You may find that when you try to import tkinter that you get an 
error. Sometimes it will tell you that you need to install another 
package. If so, follow the instructions, and try again. It may also just 
give you Python's standard error message: ModuleNotFoundError: 
No module named 'tkinter’. 


Q If you're getting an error saying No module named tkinter (without the 
single quotes around the module name), you're probably using Python 
2. This book assumes Python 3. 


Sometimes Linux distributions separate out their Tkinter support into 
a separate package. That saves installing the Tcl/Tk libraries for 
people who are using Python but not Tkinter. If so, you'll need to find 


and install this package, which wiil also ensure that an appropriate 
version of the Tcl/Tk libraries are installed on your system. 

For example, running Ubuntu 20.04LTS, Python 3.8.2 is already 
installed. However, to use Tkinter, you need to install a separate 
package, named python3-tk: 


% sudo apt-get install python3-tk 


In this case, that package provides Tcl/Tk 8.6.x libraries to be used 
with Python. 


Option 2. Install Tcl/Tk and Compile the Standard Python 
Distribution 


If you'd like to use the standard source distribution from python.org, 
you can certainly do that. 

But to do so, you'll need to get the Tcl and Tk include files and 
libraries loaded on your machine first. Again, while there are several 
ways to do that, the easiest is to download and install ActiveTcl. 


Another option would be to install the Tk development package, e.g. 
tk8 .6-dev via your package manager. 


In your web browser, go to www.activestate.com/products/activetcl. 
Download the latest version of ActiveTcl for Linux. Make sure you're 
downloading an 8.6 or newer version. Note that you will need to 
create an account with ActiveState (no cost) to download it. After it's 
downloaded, unpack it, run the installer (sudo ./install.sh), and 
follow along. You'll end up with a fresh install of ActiveTcl, located in 
€.9. /opt/ActiveTcl-8 .6. 

Next, download the current Python 3.x source distribution from 
python.org, and unpack it. On your configure line, you'll need to tell it 
how to find the version of Tcl/Tk you installed. Then build as usual: 


S$ ./configure --with-tcltk-includes=' -I/opt/ActiveTcl- 
8 .6/include' 

--with-tcltk-libs=' /opt/ActiveTcl-8 .6/1lib/1libtcl8 .6.so 
/opt/ActiveTcl-8 .6/1lib/1ibtk8 .6.so' 


foe) 


make 
% make install 


Q If you installed «xs .6-dev via your package manager instead of using 

Active Tcl, the include files should be found in /usr/ include/tci8 .6, and 

the libraries libtcl8.6.so and = libtk8.6.so Should be_ in 
/usr/lib/x86 6 4-linux-gnu. 


Make sure to verify your install (see below). 


Q Didn't work? There may have been an error compiling Python's tkinter 
code. To check, from the main Python source directory, try touch 
Modules/ tkinter.c (note the underscore) and then make to recompile 

it. Watch closely for error messages. 


The most common thing is that the way you specified the Tcl/Tk include and 
libraries needs to be changed somehow. Or if you get messages that certain 
include files can't be found (e.g. x11/xlib.hn) you may need to install additional 
packages on your Linux distribution (e.g. apt-get install libxli-dev). Once 
you get it to compile without errors, don't forget to make install. 


Verifying your Install 
At the Python command prompt, enter these two commands: 


>>> import tkinter 
>>> tkinter. test() 


This should pop up a small window; the first line at the top of the 
window should say "This is Tcl/Tk version 8.6"; make sure it is not 
8.4! 

If it gives you an error when you try to import tkinter (e.g. "If this 
fails your Python may not be configured for Tk"), something hasn't 
been set up correctly. If you compiled Python yourself, see above to 
check for compile errors. 


Get an error saying No module named tkinter? You're probably using 
Python 2. This book assumes Python 3. 


You can also get the exact version of Tcl/Tk that is being used with: 
>>> tkinter.Tcl().eval(' info patchlevel' ) 


It should return something like '8.6.9". 


AXE. Verified install using Active Tcl 8.6.9.8609.2 and Python 3.90rc1 source 
code from python.org on Ubuntu 20.04LTS. 


3.4. The Obligatory First Program 


To make sure that everything actually did work, let's try to run a 
"Hello World" program in Tk. While for something this short, you 
could just type it in directly to the interpreter, instead use your 
favorite text editor to put it in a file. 


from tkinter import * 
from tkinter import ttk 
root = Tk() 
ttk.Button(root, text="Hello World") .grid() 
root.mainloop() 


https://tkdocs.com/code/hello.py 


Save this to a file named "hello.py". From a command prompt, type: 


% python hello.py 


Couldn't find hello.py? You might be looking in the wrong directory. Try 
providing the full path to hello.py. 


macOS Windows Linux 
@ © @ he... 9 wi & r 
Hello World 


Hello World Hello World | 


Our first program. Some work left to do before the IPO. 


4. A First (Real) Example 


With that out of the way, let's try a slightly more substantial example, 
which will give you an initial feel for what the code behind a real Tk 
program looks like. 


4.1. Design 


We'll create a simple GUI tool to convert a distance in feet to the 
equivalent distance in meters. If we were to sketch this out, it might 
look something like this: 


[| feet 


is equivalentto @BQ@QGBA meters 
Calculate 


A sketch of our feet to meters conversion program. 


So it looks like we have a short text entry widget that will let us type in 
the number of feet. A "Calculate" button will get the value out of that 
entry, perform the calculation, and put the result in a label below the 
entry. We've also got three static labels ("feet," "is equivalent to," and 
"meters"), which help our user figure out how to work the application. 

The next thing we need to do is look at the layout. The widgets that 
we've included seem to be naturally divided into a grid with three 
columns and three rows. In terms of layout, things seem to naturally 
divide into three columns and three rows, as illustrated below: 


Feet to Meters ee ae 


ee ee 


The layout of our user interface, which follows a 3 x 3 grid. 


4.2. Code 


Now here is the Python code needed to create this entire application 
using Tkinter. 


from tkinter import * 
from tkinter import ttk 


def calculate (*args): 
EBy:% 
value = float (feet.get()) 
meters.set(int(0.3048 * value * 10000.0 + 
0.5)/10000.0) 
except ValueError: 
pass 


root = Tk() 
root.title("Feet to Meters") 


mainframe = ttk.Frame(root, padding="3 3 12 12") 
mainframe.grid(column=0, row=0, sticky=(N, W, E, S)) 
root.columnconfigure(0, weight=1) 
root.rowconfigure(0, weight=1) 


feet = StringVar () 
feet_entry = ttk.Entry(mainframe, width=7, textvariable=feet) 
feet_entry.grid(column=2, row=1, sticky=(W, E)) 


meters = StringVar () 
ttk.Label (mainframe, textvariable=meters) .grid(column=2, 
row=2, sticky=(W, E)) 


ttk.Button(mainframe, text="Calculate", 
command=calculate) .grid(column=3, row=3, sticky=W) 


ttk.Label (mainframe, text="feet") .grid(column=3, row=1, 
sticky=W) 
ttk.Label (mainframe, text="is equivalent to") .grid(column=1, 
row=2, sticky=BE) 

ttk.Label (mainframe, text="meters").grid(column=3, row=2, 
sticky=W) 


for child in marnirane.winto chiddren{) 4 


child.grid_ configure (padx=5, pady=5) 


féet. entry.focus {) 
root.bind("<Return>", calculate) 


root.mainloop () 


[=] https://tkdocs.com/code/f2m.py 


And the resulting user interface: 
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Linux 


n feet 


is equivalentto 0.3048 meters 


Calculate 


Screenshot of our completed feet to meters user interface. 


A Note on Coding Style 


As you know, larger Python programs are almost always structured 
into objects, classes, modules, etc. Because the focus of this book is 
Tk and Tkinter, we'll keep things as simple as possible, generally 
using a very direct and procedural coding style, rather than wrapping 


up most of our code in functions or objects. 


4.3. Step-by-Step Walkthrough 


Let's take a closer look at that code, piece by piece. For now, all 
we're trying to do is get a basic understanding of the types of things 
we need to do to create a user interface in Tk, and roughly what 
those things look like. We'll go into details later. 


Incorporating Tk 
Our program starts by incorporating Tk. 


from tkinter import * 
from tkinter import ttk 


These two lines tell Python that our program needs two modules. The 
first, tkinter, is the standard binding to Tk. When imported, it loads 
the Tk library on your system. The second, ttk, is a submodule of 
tkinter. It implements Python's binding to the newer "themed 
widgets" that were added to Tk in 8.5. 


Notice that we've imported everything (*) from the tkinter module. That 
way, we can call tkinter functions etc. without prefixing them with the 
module name. This is standard Tkinter practice. 


However, because we've imported just «tx itself, we'll need to prefix anything 
inside that submodule. For example, calling entry(...) would refer to the entry 
class inside the tkinter module (classic widgets). We'd need ttk.mntry(...) to 
use the Entry class inside tt (themed widgets). 


As you'll see, several classes are defined in both modules. Sometimes you will 
need one or the other, depending on the context. Explicitly requiring the ttk 
prefix facilitates this, and will be the style used in this book. 


One of the first things you'll find if you're migrating Python 2.x code is 
that the name of the Tkinter module is now lowercase, i.€. tkinter, 
rather than tkinter. In Python 2.x, ttk was also its own module, not a 
sub-module of tkinter. 


UPGRADE 
Peescatscstey 


Setting up the Main Application Window 


Next, the following code sets up the main application window, giving it 
the title "Feet to Meters." 


root = Tk() 
root.title("Feet to Meters") 


AX. Yes, the calculate function appeared before this. We'll describe it down 
below, but need to include it near the start because we reference it in 
other parts of the program. 


Creating a Content Frame 


Next, we create a frame widget, which will hold the contents of our 
user interface. 


mainframe = ttk.Frame(root, padding="3 3 12 12") 
mainframe.grid(column=0, row=0, sticky=(N, W, E, S)) 
root.columnconfigure(0, weight=1) 
root.rowconfigure(0, weight=1) 


After the frame is created, gria places it directly inside our main 
application window. The columnconfigure/rowconfigure bits tell Tk 
that the frame should expand to fill any extra space if the window is 
resized. 


Why do we put a frame inside the main window? Strictly speaking, we 
“sma — Could just put the other widgets in our interface directly into the main 

application window, without the intervening content frame. That's what 
you'll see in older Tk programs. 


However, the main window isn't itself part of the newer "themed" widgets. Its 
background color doesn't match the themed widgets we will put inside it. Using 
a "themed" frame widget to hold the content ensures that the background is 
correct. This is illustrated below. 


| Bom ) Without Inner Frame 


Find: 

Options: Regular expression Match case Whole word 
Find Close 

eee With Inner Frame 

5 i . 

Find: | | 

Options: Regular expression Match case Whole word 
Find Close 


Placing a themed frame inside a window. 


On macOS, where this problem is most prominent, you can also set the 
window's background color (via itS background configuration option) to the 
predefined color syst emWindowHeaderBackground. 


Creating the Entry Widget 


The first widget we'll create is the entry where we can input the 
number of feet that we want to convert. 


feet = StringVar () 
feet_entry = ttk.Entry(mainframe, width=7, textvariable=feet) 
feet_entry.grid(column=2, row=1, sticky=(W, E)) 


We need to do two things: create the widget itself, and then place it 
onscreen. 

When we create a widget, we need to specify its parent, which is 
the widget that this widget will be placed inside. In this case, we want 
our entry placed inside the content frame. Our entry, and other 
widgets we'll create shortly, are said to be children of the content 
frame. The parent is always the first parameter passed when 
instantiating a widget object. 

When we create a widget, we can optionally provide it with certain 
configuration options. Here, we specify how wide we want the entry to 


appear, i.e. 7 characters. We also assign it a mysterious 
textvariable; we'll see what that does shortly. 

When widgets are created, they don't automatically show up on the 
screen, because Tk doesn't know how you want them to be placed 
relative to other widgets. That's what the gria part does. Remember 
the layout grid when we sketched out our application? Widgets are 
placed in the appropriate column (1, 2, or 3), and row (also 1, 2, or 3). 

The sticky option to grid describes how the widget should line up 
within the grid cell, using compass directions. So w (west) means to 
anchor the widget to the left side of the cell, (w, =) (west-east) 
means to attach it to both the left and right sides, and so on. 


Creating the Remaining Widgets 


We then do exactly the same thing for the remaining widgets. We 
have one label that will display the resulting number of meters that we 
calculate. We have a "Calculate" button that is pressed to perform the 
calculation. Finally, we have three static text labels to make it clear 
how to use the application. For each of these widgets, we first create 
it and then place it onscreen in the appropriate cell in the grid. 


meters = StringVar () 
ttk.Label (mainframe, textvariable=meters) .grid(column=2, 
row=2, sticky=(W, E)) 


ttk.Button(mainframe, text="Calculate", 
command=calculate) .grid(column=3, row=3, sticky=W) 


ttk.Label (mainframe, text="feet") .grid(column=3, row=1, 
sticky=W) 
ttk.Label (mainframe, text="is equivalent to") .grid(column=1, 
row=2, sticky=BE) 

ttk.Label (mainframe, text="meters").grid(column=3, row=2, 
sticky=W) 


Adding Some Polish 
We then put a few finishing touches on our user interface. 


for child in mainframe.winfo children) : 
child.grid configure (padx=5, pady=3) 


Feet entry.f£ocus () 
root.bind("<Return>", calculate) 


The first part walks through all of the widgets that are contained 
within our content frame, and adds a little bit of padding around each, 
so they aren't so scrunched together. (We could have added these 
options to each gria call when we first put the widgets onscreen, but 
this is a nice shortcut.) 

The second part tells Tk to put the focus on our entry widget. That 
way, the cursor will start in that field, so users don't have to click in it 
before starting to type. 

The third line tells Tk that if a user presses the Return key (Enter 
on Windows) it should call our calculate routine, the same as if they 
pressed the Calculate button. 


Performing the Calculation 


Speaking of which, here we define our calculate procedure. It's called 
when a user presses the Calculate button or hits the Return key. It 
performs the feet to meters calculation. 


def calculate (*args): 
Cry? 
value = float(feet.get()) 
meters.set(int(0.3048 * value * 10000.0 + 
0.5)/10000.0) 
except ValueError: 
pass 


As you can clearly see, this routine takes the number of feet from our 
entry widget, does the calculation, and places the result in our label 
widget. 

Say what? It doesn't look like we're doing anything with those 
widgets! Here's where the magic textvariable options we specified 
when creating the widgets come into play. We specified the global 
variable feet as the textvariable for the entry, which means that 
anytime the entry changes, Tk will automatically update the global 
variable feet. Similarly, if we explicitly change the value of a 
textvariable associated with a widget (as we're doing for meters which 


is attached to our label), the widget will automatically be updated with 
the current contents of the variable. The only caveat is that these 
variables must be an instance of the stringvar Class. Slick. 


AX. The multiplying and dividing by 10000.0 is to avoid the rounding 
problems inherent in floating-point math. A simple calculation, e.g., 
0.3048*1.5, Could result in a number like 0.45720000000000005, which 

would neither be correct or visually appealing when displayed. You could also 

use Python's built-in cound() function. 


Start the Event Loop 


Finally, we need to tell Tk to enter its event loop, which is necessary 
for everything to appear onscreen and allow users to interact with it. 


root.mainloop () 


4.4. What's Missing 


We've now seen how to create widgets, put them onscreen, and 
respond to users interacting with them. It's certainly not fancy, could 
probably do with some error checking, but it's a fully-functional GUI 
application. 

It's also worth examing what we didn't have to include in our Tk 
program to make it work. For example: 


e we didn't have to worry about redrawing the screen as things 
changed 


¢ we didn't have to worry about parsing and dispatching events, hit 
detection, or handling events on each widget 


e we didn't have to provide a lot of options when we created 
widgets; the defaults seemed to take care of most things, and so 
we only had to change things like the text the button displayed 


e we didn't have to write complex code to get and set the values of 
simple widgets; we just attached them to variables 


e we didn't have to worry about what happens when users close 
the window or resizes it 


e we didn't need to write extra code to get this all to work cross- 
platform 


One More Thing... 


As this book emphasizes Tkinter, our examples use standalone script 
code, global variables, and simple functions. In practice, you'll likely 
organize anything beyond the simplest scripts in functions or classes. 
There are different ways to do this: using modules, creating classes 
for different parts of the user interface, inheriting from Tkinter classes, 
etc. 

Often though, you just want to do something simple to encapsulate 
your data rather than putting everything into the global variable 
space. Here is the feet to meters example, rewritten to encapsulate 


the main code into a class. Note the use of se1f on callbacks (which 
execute at the global scope) and stringvar's. 


from tkinter import * 
from tkinter import ttk 


class FeetToMeters: 
deft 1M: (6eLr, ®o6r)s 
root.title("Feet to Meters") 


mainframe = ttk.Frame(root, padding="3 3 12 12") 
mainframe.grid(column=0, row=0, sticky=(N, W, E, S)) 
root.columnconfigure(0, weight=1) 
root.rowconfigure(0, weight=1) 


self.feet = StringVar () 

feet_entry = ttk.Entry(mainframe, width=7, 
textvariable=self.feet) 

feet entry.grid(column=2, row=1l, sticky=(W, E)) 

self.meters = StringVar () 


ttk.Label (mainframe, 
textvariable=self.meters) .grid(column=2, row=2, sticky=(W, E) ) 
ttk.Button(mainframe, text="Calculate", 
command=self.calculate).grid(column=3, row=3, sticky=W) 


ttk.Label (mainframe, text="feet") .grid(column=3, 
row=1, sticky=W) 

ttk.Label (mainframe, text="is equivalent 
to") .grid(column=1, row=2, sticky=E) 

ttk.Label (mainframe, text="meters") .grid(column=3, 
row=2, sticky=W) 


for child in mainframe.winfo children(): 
child.grid_configure (padx=5, pady=5) 


feel. entry.rocus {) 
root.bind("<Return>", self.calculate) 


def calculate(self, *args): 
try: 
value = float(self.feet.get()) 
self.meters.set (int (0.3048 * value * 10000.0 + 
0.5)/10000.0) 
except ValueError: 


pass 
root = Tk() 


FeetToMeters (root) 
root.mainloop () 


https://tkdocs.com/code/f2mo.py 


5. Tk Concepts 


With your first example behind you, you now have a basic idea of 
what a Tk program looks like and the type of code you need to write 
to make it work. In this chapter, we'll step back and look at three 
broad concepts that you need to know to understand Tk: widgets, 
geometry management, and event handling. 


5.1. Widgets 


Widgets are all the things that you see onscreen. In our example, we 
had a button, an entry, a few labels, and a frame. Others are things 
like checkboxes, tree views, scrollbars, text areas, and so on. 
Widgets are often referred to as "controls." You'll also sometimes see 
them referred to as "windows," particularly in Tk's documentation. 
This is a holdover from its X11 roots (under that terminology, both 
your toplevel application window and things like a button would be 
called windows). 

Here is an example showing some of Tk's widgets, which we'll 
cover individually shortly. 
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Widget Classes 


Widgets are objects, instances of classes that represent buttons, 
frames, and so on. When you want to create a widget, the first thing 
you'll need to do is identify the specific class of the widget you'd like 
to instantiate. This book will help with that. 


Widget Hierarchy 


Besides the widget class, you'll need one other piece of information to 
create it: its parent. Widgets don't float off in space. Instead, they're 
contained within something else, like a window. In Tk, all widgets are 
part of a widget (or window) hierarchy, with a single root at the top of 
the hierarchy. 

In our metric conversion example, we had a single frame that was 
created as a child of the root window, and that frame had all the other 
controls as children. The root window was a container for the frame 
and was, therefore, the frame's parent. The complete hierarchy for 
the example looked like this: 


root 


content frame 


feet meters (result) calculate Ce equiv alent to’ 


entry label button label label label 
The widget hierarchy of the metric conversion example. 


This hierarchy can be arbitrarily deep, so you might have a button in 
a frame in another frame within the root window. Even a new window 
in your application (often called a toplevel) is part of that same 
hierarchy. That window and all its contents form a subtree of the 
overall widget hierarchy. 


Menu Toplevel Toplevel Menu Menu Toplevel Toplevel 
Frame Frame 
Frame we i Frame 
TFrame TNotebook Frame Frame Frame 
TFrame Frame Frame Frame 
Canvas 
Frame 
TFrame TFrame TFrame TFrame TFrame 
TLabelframe TLabelframe TLabelframe TLabelframe 
TFrame TFrame TFrame TFrame 
Menubutton TFrame TLabelframe Canvas 
TFrame Menubutton TFrame TFrame 
TLabelframe TLabelframe Menubutton 
Menubutton TLabelframe Menubutton 
Menubutton TFrame 
TLabelframe TLabelframe TLabelframe TLabelframe 
TFrame TFrame TFrame TFrame 
TFrame TFrame TFrame 
TFrame TFrame 
TFrame 
TMenubutton 
TFrame 
Hierarchy of a more substantial application. Leaf nodes (buttons, labels, etc.) 


omitted. 


Creating Widgets 


Each separate widget is a Python object. When instantiating a widget, 
you must pass its parent as a parameter to the widget class. The only 
exception is the "root" window, which is the toplevel window that will 
contain everything else. That is automatically created when you 
instantiate Tx. It does not have a parent. For example: 


root = Tk() 
content = ttk.Frame (root) 
button = ttk.Button(content) 


Whether or not you save the widget object in a variable is entirely up 
to you, depending on whether you'll need to refer to it later. Because 
the object is inserted into the widget hierarchy, it won't be garbage 
collected even if you don't keep your own reference to it. 


XL. If you sneak a peek at how Tcl manages widgets, you'll see each widget 
has a specific pathname; you'll also see this pathname referred to in Tk 
reference documentation. Tkinter chooses and manages all these 

pathnames for you behind the scenes, so you should never have to worry about 
them. If you do, you can get the pathname from a widget by calling str (widget). 


Configuration Options 


All widgets have several configuration options. These control how the 
widget is displayed or how it behaves. 

The available options for a widget depend upon the widget class, 
of course. There is a lot of consistency between different widget 
classes, so options that do pretty much the same thing tend to be 
named the same. For example, both a button and a label have a text 
option to adjust the text that the widget displays, while a scrollbar 
would not have a text option since it's not needed. Similarly, the 
button has a command option telling it what to do when pushed, while a 
label, which holds just static text, does not. 

Configuration options can be set when the widget is first created by 
specifying their names and values as optional parameters. Later, you 
can retrieve the current values of those options, and with a very small 
number of exceptions, change them at any time. 

If you're not sure what configuration options a widget supports, you 
can ask the widget to describe them. This gives you a long list of all 
its options. 

This is all best illustrated with the following interactive dialog with 
the interpreter. 


6 python 

>>> from tkinter import * 

>>> from tkinter import ttk 

>>> root = Tk() 

create a button, passing two options: 

>>> button = ttk.Button(root, text="Hello", 
command="buttonpressed" ) 

>>> button.grid() 

check the current value of the text option: 
>>> button[' text’ ] 

"Hello' 

change the value of the text option: 


>>> button[' text'] = ' goodbye’ 

another way to do the same thing: 

>>> button.configure (text=' goodbye' ) 

check the current value of the text option: 
>>> button[' text’ ] 

"goodbye' 

get all information about the text option: 
>>> button.configure(' text’ ) 

('text', 'text', 'Text', '', '"goodbye') 

get information on all options for this widget: 
>>> button.configure() 


{'cursor': ('cursor', 'cursor', 'Cursor', '', ''), 'style': 
('style't, "style", "Style, Ty TM )y 

"default': ('default', 'default', 'Default', <index object at 
OxOODFFD10>, <index object at OxOODFFDI1O0>), 

‘text’: ('text', 'text', 'Text', '', 'goodbye'), 'image': 
(‘image', 'image', 'Image', '', ''), 

‘elass*s (telass*, "S, 77, TY, 4), “padding': (¢"padding*, 
‘oadding*, 'Pad', va a a 

‘width': ('width', 'width', 'Width', '', ''), 

"state': ('state', 'state', 'State', <index object at 
Ox0167FA20>, <index object at Ox0167FA20>), 

‘command': ('command', 'command' , 'Command', '', 
"buttonpressed'), 

"textvariable': ('textvariable', 'textVariable', 'Variable', 
ae ae 

"compound': ('compound', 'compound', 'Compound', <index object 
at Ox0167FA08>, <index object at 0x0167FA08>), 

‘underline': ('underline', ‘underline', 'Underline', -1l, -1l), 
"takefocus': ('takefocus', 'takeFocus', 'TakeFocus', '', 


"ttk::takefocus') } 


As you can see, for each option, Tk will show you the name of the 
option and its current value (along with three other attributes which 
you won't normally need to worry about). 


fii Ok, if you really want to know, here are the details on the five pieces of 
data provided for each configuration option. The most useful are the 
first, which is the option's name, and the fifth, which is the option's 
current value. The fourth is the default value of the option, or in other words, the 
value it would have if you didn't change it. The other two relate to something 
called the option database. We'll touch on it when we discuss menus, but it's not 
something that's used in modern applications. The second item is the name of 
the option in the database, and the third is its class. 


Widget Introspection 


Tk exposes a treasure trove of information about each and every 
widget that your application can take advantage of. Much of it is 
available via the winfo facility; see the see the winfo command 
reference for full details. 


[3 https://tkdocs.com/man/winfo 


This short example traverses the widget hierarchy, using each 
widget's winfo children method to identify any child widgets that 
need to examined. For each widget, we print some basic information, 
including it's class (button, frame, etc.), it's width and height, and it's 
position relative to it's parent. 


déf print hierarchy (w, depth=0) : 


print (' “sdepth + w.winto class () + * w=" + 
str(w.winto width()) + * h=' 4+ sir(w.winto héight()) + * x=" + 
str(w.winfo x()) + ' y=' + str(w.winfo_y())) 


for A. In wWewinto Children () 4 
print hierarchy(i, depth+1) 
print_hierarchy (root) 


The following are some of the most useful methods: 


winfo class: 
a Class identifying the type of widget, e.g. TButton for a themed 
button 


winfo children: 
a list of widgets that are the direct children of a widget in the 
hierarchy 

winfto parent: 
parent of the widget in the hierarchy 

winfo_ toplevel: 
the toplevel window containing this widget 

winfo width, winfo_ height: 
current width and height of the widget; not accurate until appears 
onscreen 

winfo reqwidth, winfo_reqheight: 
the width and height the widget requests of the geometry 
manager (more on this shortly) 


winfo_ x, winfo y: 


the position of the top-left corner of the widget relative to its 
parent 


winfo rootx, winfo_rooty: 
the position of the top-left corner of the widget relative to the 


entire screen 
winfo vieweable: 


whether the widget is displayed or hidden (all its ancestors in the 
hierarchy must be viewable for it to be viewable) 


5.2. Geometry Management 


If you've been running code interactively, you've probably that just by 
creating widgets, they didn't appear onscreen. Placing widgets 
onscreen, and precisely where they are placed, is a separate step 
called geometry management. 

In our example, positioning each widget was accomplished by the 
grid command. We specified the column and row we wanted each 
widget to go in, how things were to be aligned within the grid, etc. 
Grid is an example of a geometry manager (of which there are 
several in Tk, grid being the most useful). For now, we'll look at 
geometry management in general; we'll talk about grid in a later 
chapter. 

A geometry manager's job is to figure out exactly where those 
widgets are going to be put. This turns out to be a complex 
optimization problem, and a good geometry manager relies on quite 
sophisticated algorithms. A good geometry manager provides the 
flexibility, power, and ease of use that makes programmers happy. It 
also makes it easy to create good looking user interface layouts 
without needing to jump through hoops. Tk's grid is, without a doubt, 
one of the absolute best. A poor geometry manager... well, all the 
Java programmers who have suffered through "GridBagLayout" 
please raise their hands. 


We'll go into more detail in a later chapter, but gria was introduced 
several years after Tk became popular. Before that, an older geometry 
manager named pack was most commonly used. It's very powerful, but 
is much harder to use, and makes it extremely difficult to create layouts that 
look appealing today. Unfortunately, much of the example Tk code and 
documentation out there uses pack instead of gria (a good clue to how current it 
is). The widespread use of pack is one major reason that so many Tk user 
interfaces look terrible. Start new code with gria, and upgrade old code when 
you can. 


UPGRADE 


The Problem 


The problem for a geometry manager is to take all the different 
widgets the program creates, plus the program's instructions for 
where in the window each should go (explicitly, or more often, relative 
to other widgets), and then actually position them in the window. 

In doing so, the geometry manager has to balance multiple 
constraints. Consider these situations: 


The widgets may have a natural size, e.g., the natural width of a 
label would depend on the text it displays and the font used to 
display it. What if the application window containing all these 
different widgets isn't big enough to accommodate them? The 
geometry manager must decide which widgets to shrink to fit, by 
how much, etc. 


If the application window is bigger than the natural size of all the 
widgets, how is the extra space used? Is extra space placed 
between each widget, and if so, how is that space distributed? Is 
it used to make certain widgets larger than they normally want to 
be, such as a text entry growing to fill a wider window? Which 
widgets should grow? 


If the application window is resized, how does the size and 
position of each widgets inside it change? Will certain areas 
(e.g., a text entry area) expand or shrink while other parts stay 
the same size, or is the area distributed differently? Do certain 
widgets have a minimum size that you want to avoid going 
below? A maximum size? Does the window itself have a 
minimum or maximum size? 


How can widgets in different parts of the user interface be 
aligned with each other? How much space should be left 
between them? This is needed to present a clean layout and 
comply with platform-specific user interface guidelines. 


For a complex user interface, which may have many frames 
nested in other frames nested in the window (etc.), how can all 
the above be accomplished, trading off the conflicting demands 
of different parts of the entire user interface? 


How it Works 


Geometry management in Tk relies on the concept of master and 
slave widgets. A master is a widget, typically a toplevel application 
window or a frame, which contains other widgets, called slaves. You 
can think of a geometry manager taking control of the master widget 
and deciding how all the slave widgets will be displayed within. 


XL. The computing community has embraced the more general societal 
trend towards more diversity, sensitivity, and awareness about the 
impacts of language. Recognizing this, the Tk core will slowly be 

adopting a more inclusive set of terminology. For example, where it makes 

sense, "parent" and "child" will be preferred over "master" and "slave." To 
preserve backward compatibility, the current terminology will not be 
disappearing. This is something to be aware of for the future. For more details, 


Your program tells the geometry manager what slaves to manage 
within the master, i.e., via calling grid. Your program also provides 
hints as to how it would like each slave to be displayed, e.g., via the 
column and row options. You can also provide other things to the 
geometry manager. For example, we used columnconfigure and 
rowconfigure to indicate the columns and rows we'd like to expand if 
there is extra space available in the window. It's worth noting that all 
these parameters and hints are specific to gria; other geometry 
managers would use different ones. 

The geometry manager takes all the information about the slaves 
in the master, as well as information about how large the master is. It 
then asks each slave widget for its natural size, i.e., how large it 
would ideally like to be displayed. The geometry manager's internal 
algorithm calculates the area each slave will be allocated (if any!). 
The slave is then responsible for rendering itself within that particular 
rectangle. And of course, any time the size of the master changes 
(e.g., because the toplevel window was resized), the natural size of a 
slave changes (e.g., because we've changed the text in a label), or 
any of the geometry manager parameters change (e.g., like row, 
column, OF sticky) we repeat the whole thing. 

This all works recursively as well. In our example, we had a 
content frame inside the toplevel application window, and then 
several other widgets inside the content frame. We, therefore, had to 
manage the geometry for two different masters. At the outer level, the 


toplevel window was the master, and the content frame was its slave. 
At the inner level, the content frame was the master, with each of the 
other widgets being slaves. Notice that the same widget, e.g., the 
content frame, can be both a master and a slave! As we saw 
previously, this widget hierarchy can be nested much more deeply. 


AXE. While each master can be managed by only one geometry manager 

(e.g. grid), different masters can have different geometry managers. 

While gria is the right choice most of the time, others may make sense 

for a particular layout used in one part of your user interface. Other Tk geometry 

managers include pack, which we've mentioned, and piace, which leaves all 

layout decisions entirely up to you. Some complex widgets like canvas and text 
let you embed other widgets, making them de facto geometry managers. 


Finally, we've been making the assumption that slave widgets are the 
immediate children of their master in the widget hierarchy. While this is usually 
the case, and mostly there's no good reason to do it any other way, it's also 
possible (with some restrictions) to get around this. 


5.3. Event Handling 


Tk, as with most other user interface toolkits, runs an event loop that 
receives events from the operating system. These are things like 
button presses, keystrokes, mouse movement, window resizing, and 
so on. 

Generally, Tk takes care of managing this event loop for you. It will 
figure out what widget the event applies to (did a user click on this 
button? if a key was pressed, which textbox had the focus?), and 
dispatch it accordingly. Individual widgets know how to respond to 
events; for example, a button might change color when the mouse 
moves over it, and revert back when the mouse leaves. 


Qa It's critical in event-driven applications that the event loop not be 
blocked. The event loop should run continuously, normally executing 
dozens of steps per second. At every step, it processes an event. If 

your program is performing a long operation, it can potentially block the event 
loop. In that case, no events would be processed, no drawing would be done, 
and it would appear as if your application is frozen. There are many ways to 
avoid this happening, mostly related to the structure of your application. We'll 
discuss this in more detail in a later chapter. 


Command Callbacks 


You often want your program to handle some event in a particular 
way, e€.g., do something when a button is pushed. For those events 
that are most frequently customized (what good is a button without 
something happening when you press it?), the widget will allow you to 
specify a callback as a widget configuration option. We saw this in the 
example with the command option of the button. 


def calculate (*args): 


ttk.Button(mainframe, text="Calculate", command=calculate) 


Callbacks in Tk tend to be simpler than in user interface toolkits used 
with compiled languages (where a callback must be a procedure with 
a certain set of parameters or an object method with a certain 
signature). Instead, the callback is just an ordinary bit of code that the 
interpreter evaluates. While it can be as complicated as you want to 
make it, most of the time, you'll just want your callback to call some 
other procedure. 


Binding to Events 


For events that don't have a widget-specific command callback 
associated with them, you can use Tk's bina to capture any event, 
and then (like with callbacks) execute an arbitrary piece of code. 

Here's a (silly) example showing a label responding to different 
events. When an event occurs, a description of the event is displayed 
in the label. 


from tkinter import * 

from tkinter import ttk 

root = Tk() 

1 =ttk.Label (root, text="Starting...") 

l.grid() 

l.bind('<Enter>', lambda e: 1l.configure(text='Moved mouse 
inside')) 
l.bind('<Leave>', lambda e: 1l.configure(text='Moved mouse 
outside')) 

1.bind('<ButtonPress-1>', lambda e: 1.configure(text='Clicked 
left mouse button')) 

1l.bind('<3>!', lambda e: 1.configure(text='Clicked right mouse 
button')) 

1.bind('<Double-1>', lambda e: 1.configure (text='Double 
clicked') ) 

1.bind('<B3-Motion>', lambda e: 1.configure(text='right button 
drag to %d,%d' % (e.x, e.y))) 

root.mainloop () 


The first two bindings are pretty straightforward, just watching for 
simple events. An <Enter> event means the mouse has moved over 
top the widget, while the <Leave> event is generated when the mouse 
moves outside the widget to a different one. 


The next binding looks for a mouse click, specifically a 
<ButtonPress-1> event. Here, the <ButtonPress> is the actual event, 
but the -1 is an event detail specifying the left (main) mouse button 
on the mouse. The binding will only trigger when a <ButtonPress> 
event is generated involving the main mouse button. If another 
mouse button was clicked, this binding would ignore it. 

This next binding looks for a <3> event. This is actually a shorthand 
for <ButtonPress-3>. It will respond to events generated when the 
right mouse button is clicked. The next binding, <Double-1> 
(shorthand for <Double-ButtonPress-1>) adds another modifier, 
Double, and so will respond to the left mouse button being double 
clicked. 

The last binding also uses a modifier: capture mouse movement 
(Motion), but only when the right mouse button (83) is held down. This 
binding also shows an example of how to use event parameters. 
Many events, such as mouse clicks or movement carry additional 
information like the current position of the mouse. Tk provides access 
to these parameters in Tcl callback scripts through the use of percent 
substitutions. These percent substitutions let you capture them so 
they can be used in your script. 

Tkinter abstracts away these percent substitutions and instead 
encapsulates all the event parameters in an event object. Above, we 
used the x and y fields to retrieve the mouse position. We'll see 
percent substitutions used later in another context, entry widget 
validation. 


XL. What's with the lambda expressions? Tkinter expects you to provide a 
function as the event callback, whose first argument is an event object 
representing the event that triggered the callback. It's sometimes not 

worth the bother of defining regular named functions for one-off trivial callbacks 
such as in this example. Instead, we've just used Python's anonymous functions 
via lambda. In real applications, you'll almost always use a regular function, such 
as the calculate function in our feet to meters example, or a method of an 
object. 


Multiple Bindings for an Event 


We've just seen how event bindings can be set up for an individual 
widget. When a matching event is received by that widget, the 
binding will trigger. But that's not all you can do. 

Your binding can capture not just a single event, but a short 
sequence of events. The <Double-1> binding triggers when two 
mouse clicks occur in a short time. You can do the same thing to 
capture two keys pressed in a row, @€.g., <KeyPress-A><KeyPress-B> OF 
simply <ab>. 

You can also set up an event binding on a toplevel window. When 
a matching event occurs anywhere in that window, the binding will be 
triggered. In our example, we set up a binding for the Return key on 
the main application toplevel window. If the Return key was pressed 
when any widget in the toplevel window had the focus, that binding 
would fire. 

Less commonly, you can create event bindings that are triggered 
when a matching event occurs anywhere in the application, or even 
for events received by any widget of a given class, e.g., all buttons. 


XL. More than one binding can fire for an event. This keeps event handlers 
concise and limited in scope, meaning more modular code. For 
example, the behavior of each widget class in Tk is itself defined with 

script-level event bindings. These stay separate from event bindings in your 
application. Event bindings can also be changed or deleted. They can be 
modified to alter event handling for widgets of a certain class or parts of your 
application. You can reorder, extend, or change the sequence of event bindings 
that will be triggered for each widget; see the bindtags command reference if 
youre Curious. 

= https: /Akdocs.com/man/bindtags 


Available Events 


The most commonly used events are described below, along with the 
circumstances when they are generated. Some are generated on 
some platforms and not others. For a complete description of all the 
different event names, modifiers, and the different event parameters 
that are available with each, the best place to look is the bina 
command reference. 


[3 https://tkdocs.com/man/bind 


<Activate>: 

Window has become active. 
<Deactivate>: 

Window has been deactivated. 
<MouseWheel>: 

Scroll wheel on mouse has been moved. 
<KEVPresis?? 

Key on keyboard has been pressed down. 
<KeyRelease>: 

Key has been released. 
<ButtonPress>: 

A mouse button has been pressed. 
<ButtonRelease>: 

A mouse button has been released. 
<Motion>: 

Mouse has been moved. 
<Configure>: 


Widget has changed size or position. 
<Destroy>: 

Widget is being destroyed. 
<rocus i n>% 

Widget has been given keyboard focus. 
<FocusOut>: 

Widget has lost keyboard focus. 
<EnCEer>: 

Mouse pointer enters widget. 
<Leave>: 

Mouse pointer leaves widget. 


Event detail for mouse events are the button that was pressed, e.g. 1, 
2, or 3. For keyboard events, it's the specific key, €.g. A, 9, space, plus, 
comma, equal. A complete list can be found in the keysyms command 
reference. 


[3 https://tkdocs.com/man/keysyms 


Event modifiers for include, e.g. 81 Or Buttoni to signify the main 
mouse button being held down, Double Or Triple for Sequences of the 


same event. Key modifiers for when keys on the keyboard are held 
down inline control, Shift, Alt, Option, ANd Command. 


Virtual Events 


The events we've seen so far are low-level operating system events 
like mouse clicks and window resizes. Many widgets also generate 
higher level or semantic events called virtual events. These are 
indicated by double angle brackets around the event name, e.g., 
<<fOGr>. 

For example, a listbox widget will generate a <<ListboxSelect>> 
virtual event whenever its selection changes. The same virtual event 
is generated whether a user clicked on an item, moved to it using the 
arrow keys, or some other way. Virtual events avoid the problem of 
setting up multiple, possibly platform-specific event bindings to 
capture common changes. The available virtual events for a widget 
will be listed in the documentation for the widget class. 

Tk also defines virtual events for common operations that are 
triggered in different ways for different platforms. These include 
<<Cut>>, <<Copy>> and <<Paste>>. 

You can define your own virtual events, which can be specific to 
your application. This can be a useful way to keep platform-specific 
details isolated in a single module, while you use the virtual event 
throughout your application. Your own code can generate virtual 
events that work in exactly the same way that virtual events 
generated by Tk do. 


rool.event generate ("<<MyOwnEvent>>") 


6. Basic Widgets 


This chapter introduces the basic Tk widgets that you'll find in just 
about any user interface: frames, labels, buttons, checkbuttons, 
radiobuttons, entries, and comboboxes. By the end, you'll know how 
to use all the widgets you'd ever need for a typical fill-in-the-form 
type of user interface. 

You'll find it easiest to read this chapter (and those following that 
discuss more widgets) in order. Because there is so much 
commonality between many widgets, we'll introduce certain concepts 
when describing one widget that will also apply to a widget we 
describe later. Rather than going over the same ground multiple 
times, we'll refer back to when the concept was first introduced. 

At each widget is introduced, we'll note the Tkinter class used to 
create the widget and its Tk reference manual page. Even though 
this reference documentation refers to the Tcl interface to Tk, it is the 
most accurate and complete description of each Tk widget. The 
internals of Python's Tkinter module directly rely on this Tcl interface. 
As a reminder, this book highlights the most useful parts of Tk and 
how to use them to build effective modern user interfaces. The 
reference documentation, which details everything that can be done 
in Tk, serves a very different purpose. 


6.1. Frame 
nat ttk.Frame 
[3 https://tkdocs.com/man/ttk_frame 


A frame is a widget that displays as a simple rectangle. Frames help 
to organize your user interface, often both visually and at the coding 
level. Frames often act as master widgets for a geometry manager 
like grid, which manages the slave widgets contained within the 
frame. 


macOSs Windows Linux 


Frame widgets. 


Frames are created using the ttk.Frrame Class: 


frame = ttk.Frame (parent) 


Frames can take several different configuration options, which can 
alter how they are displayed. 


Requested Size 
Typically, the size of a frame is determined by the size and layout of 


any widgets within it In turn, this is controlled by the geometry 
manager that manages the contents of the frame itself). 


If, for some reason, you want an empty frame that does not 
contain other widgets, you can instead explicitly set its size using the 
width and/or height configuration options (otherwise, you'll end up 
with a very small frame indeed). 

Screen distances such as width and height are usually specified 
as a number of pixels screen. You can also specify them via one of 
several suffixes. For example, 350 means 350 pixels, 350c means 
350 centimeters, 350m means 350 millimeters, 3501 means 350 
inches, and 350p means 350 printer's points (1/72 inch). 


Remember, if you request that a frame (or any widget) to have a given 
size, the geometry manager has the final say. If things aren't showing 
up the way you want them, make sure to check there too. 


Padding 


The padding configuration option is used to request extra space 
around the inside of the widget. If you're putting other widgets inside 
the frame, there will be a bit of a margin all the way around. You can 
specify the same padding for all sides, different horizontal and 
vertical padding, or padding for each side separately. 


f['padding'] = 5 # 5 pixels on all sides 
f['padding'] = (5,10) # 5 on left and right, 10 on top 
and bottom 

€[*padding’]).— (5,7;10,12) ¢ fete: 6, toon 7, tigre, 10, 
bottom: 12 

Borders 


You can display a border around a frame widget to visually separate 
it from its surroundings. You'll see this often used to make a part of 
the user interface look sunken or raised. To do this, you need to set 
the borderwidth configuration option (which defaults to 0, i.e., no 
border), and the relief option, which specifies the visual 
appearance of the border. This can be one of: fiat (default), raisea, 


sunken, solid, ridge, Ol groove. 


frame['borderwidth'] = 2 
frame['relief'] = 'sunken' 


Changing Styles 


Frames have a style configuration option, which is common to all of 
the themed widgets. This lets you control many other aspects of their 
appearance or behavior. This is a bit more advanced, so we won't go 
into it in too much detail right now. But here's a quick example of 
creating a "Danger" frame with a red background and a raised 
border. 


s = ttk.Style() 

s.configure('Danger.TFrame', background='red', borderwidth=5, 
relief='raised') 

ttk.Frame (root, width=200, height=200, 
style='Danger.TFrame') .grid() 


AX. What elements of widgets can be changed by styles vary by widget 
and platform. On Windows and Linux, it does what you'd expect. On 
current macOS, the frame will have a red raised border, but the 

background will remain the default grey. Much more on why this is in a later 
chapter. 


<) Styles mark a sharp departure from how most aspects of a widget's 
“amas Visual appearance were changed in the "classic" Tk widgets. In classic 

Tk, you could provide a wide range of options to finely control every 
aspect of an individual widget's behavior, e.g., foreground color, background 
color, font, highlight thickness, selected foreground color, and padding. When 
using the new themed widgets, these changes are made by modifying styles, 


not adding options to each widget. 


As such, many options you may be familiar with in certain classic widgets are 
not present in their themed version. However, overuse of such options was a 
key factor undermining the appearance of Tk applications, especially when 
used across different platforms. Transitioning from classic to themed widgets 
provides an opportune time to review and refine how (and if!) such appearance 
changes are made. 


6.2. Label 


Pl ttk.tabel 


[3 https://tkdocs.com/man/ttk_label 


A label is a widget that displays text or images, typically that users 
will just view but not otherwise interact with. Labels are used for to 
identify controls or other parts of the user interface, provide textual 
feedback or results, etc. 


macOS Windows Linux 
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Figure 1. Figure 1. Figure 1. 
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Name must not be blank. Name must not be blank. Name must not be blank. 
Label widgets. 


Labels are created using the ttk.Label class. Often, the text or 
image the label will display are specified via configuration options at 
the same time: 


label = ttk.Label (parent, text='Full name:') 


Like frames, labels can take several different configuration options, 
which can alter how they are displayed. 


Displaying Text 


The text configuration option (shown above when creating the label) 
is the most commonly used, particularly when the label is purely 
decorative or explanatory. You can change what text is displayed by 
modifying this configuration option. This can be done at any time, not 
only when first creating the label. 


You can also have the widget monitor a variable in your script. 
Anytime the variable changes, the label will display the new value of 
the variable. This is done with the textvariable option: 


resultsContents = StringVar () 
label ['textvariable'] = resultsContents 
resultsContents.set('New value to display') 


Tkinter only allows you to attach widgets to an instance of the 
Stringvar Class, and not arbitrary Python variables. This class 
contains all the logic to watch for changes and communicate them 
back and forth between the variable and Tk. Use the get and set 
methods to read or write the current value of the variable. 


Displaying Images 


Labels can also display an image instead of text. If you just want an 
image displayed in your user interface, this is normally the way to do 
it. We'll go into images in more detail in a later chapter, but for now, 
let's assume you want to display a GIF stored in a file on disk. This is 
a two-step process. First, you will create an image "object." Then, 
you can tell the label to use that object via its image configuration 
option: 


image = PhotoImage (file='myimage.gif') 
label['image'] = image 


Labels can also display both an image and text at the same time. 
You'll often see this in toolbar buttons. To do so, use the compound 
configuration option. The default value is none, meaning display only 
the image if present; if there is no image, display the text specified 
by the text Of textvariable options. Other possible values for the 
compound option are: text (text only), image (image only), conver (text 
in the center of image), top (image above text), left, bottom, and 
FLgHt. 


Fonts, Colors, and More 


Like with frames, you normally don't want to change things like fonts 
and colors directly. If you need to change them (e.g., to create a 
special type of label), the preferred method would be to create a new 
style, which is then used by the widget with the style option. 

Unlike most themed widgets, the label widget also provides 
explicit widget-specific configuration options as an alternative. Again, 
you should use these only in special one-off cases when using a 
style didn't necessarily make sense. 

You can specify the font used to display the label's text using the 
font Configuration option. While we'll go into fonts in more detail in a 
later chapter, here are the names of some predefined fonts you can 
use: 


TkDefaultFont: 

Default for all GUI items not otherwise specified. 
TkTextFont: 

Used for entry widgets, listboxes, etc. 
TkFixedFont: 

A standard fixed-width font. 

TkMenuFont: 

The font used for menu items. 

TkHeadingFont: 
A font for column headings in lists and tables. 
TkCaptionFont: 
A font for window and dialog caption bars. 
TkSmallCaptionFont: 

Smaller captions for subwindows or tool dialogs. 
TkIlconFont: 

A font for icon captions. 

TkTooltipFont: 

A font for tooltips. 


Q Because font choices are so platform-specific, be careful of hardcoding 
specifics (font families, sizes, etc.). This is something else you'll see in 
many older Tk programs that can make them look ugly. 


label['font'] = "TkDefaultFont" 


The foreground (text) and background color of the label can also be 
changed via the foreground and background configuration options. 
Colors are covered in detail later, but you can specify them as either 
color names (e.g., rea) or hex RGB codes (e.g., #££340a). 

Labels also accept the reiier configuration option discussed for 
frames to make them appear sunken or raised. 


Layout 


While the overall layout of the label (i.e., where it is positioned within 
the user interface, and how large it is) is determined by the geometry 
manager, several options can help you control how the label will be 
displayed within the rectangle the geometry manager gives it. 

If the box given to the label is larger than the label requires for its 
contents, you can use the anchor option to specify what edge or 
corner the label should be attached to, which would leave any empty 
space in the opposite edge or corner. Possible values are specified 
as compass directions: n (north, or top edge), ne, (north-east, or top 
right corner), e, se, s, sw, w, nw Of center. 


Things not appearing where you think they should? It may be that the 

geometry manager is not putting the label where you think it is. For 

example, if you're using gria, you may need to adjust the sticky 
options. When debugging, it can help to change the background color of each 
widget, so you know exactly where each Is positioned. This is a good example 
of those "one-off" cases we just mentioned where you might use configuration 
options rather than styles to modify appearance. 


Multi-line Labels 


Labels can display more than one line of text. To do so, embed 
carriage returns (\n) in the text (Or textvariable) string. Labels can 
also automatically wrap your text into multiple lines via the 
wraplength Option, which specifies the maximum length of a line (in 
pixels, centimeters, etc.). 


Multi-line labels are a replacement for the older message widgets in classic Tk. 
y™ 


— You can also control how the text is justified via the justify 

option. It can have the values left, center, OF right. If you 

have only a single line of text, you probably want the anchor option 
instead. 


6.3. Button 


EO. tk Button 


[3 https://tkdocs.com/man/ttk_button 


A button, unlike a frame or label, is very much there to interact with. 
Users press a button to perform an action. Like labels, they can 
display text or images, but accept additional options to change their 
behavior. 


macOS Windows Linux 
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Button widgets. 


Buttons are created using the ttk.Button Class: 


button = ttk.Button(parent, text='Okay', command=submitForm) 


Typically, their contents and command callback are specified at the 
same time. As with other widgets, buttons can take several different 
configuration options, including the standard style option, which can 
alter their appearance and behavior. 


Text or Image 


Buttons take the same text, textvariable (rarely used), image, and 
compound configuration options as labels. These control whether the 
button displays text and/or an image. 


Buttons have a default configuration option. If specified as 
active, this tells Tk that the button is the default button in the user 
interface; otherwise it is normal. Default buttons are invoked if users 
hit the Return or Enter key). Some platforms and styles will draw this 
default button with a different border or highlight. Note that setting 
this option doesn't create an event binding that will make the Return 
or Enter key activate the button; that you have to do yourself. 


The Command Callback 


The command option connects the button's action and your application. 
When a user presses the button, the script provided by the option is 
evaluated by the interpreter. 

You can also ask the button to invoke the command callback from 
your application. That way, you don't need to repeat the command to 
be invoked several times in your program. If you change the 
command attached to the button, you don't need to change it 
elsewhere too. Sounds like a useful way to add that event binding on 
our default button, doesn't it? 


action = ttk.Button(root, text="Action", default="active", 
command=myaction) 
root.bind('<Return>', lambda e: action.invoke()) 


Standard behavior for dialog boxes and many other windows on most 

platforms is to set up a binding on the window for the Return key 

(<Return> Of <Key-Return>) to invoke the active button if it exists, as 
we've done here. If there is a "Close" or "Cancel" button, create a binding to 
the Escape key (<key-Escape>). On macOS, you should additionally bind the 
Enter key on the keyboard (<xp Enter>) to the active button, and Commanda- 
period (<command-.>) to the close or cancel button. 


Button State 


Buttons and many other widgets start off in a normal state. A button 
will respond to mouse movements, can be pressed, and will invoke 
its command callback. Buttons can also be put into a disabled state, 


where the button is greyed out, does not respond to mouse 
movements, and cannot be pressed. Your program would disable the 
button when its command is not applicable at a given point in time. 

All themed widgets maintain an internal state, represented as a 
series of binary flags. Each flag can either be set (on) or cleared 
(off). You can set or clear these different flags, and check the current 
setting using the state and instate methods. Buttons make use of 
the disabled flag to control whether or not users can press the 
button. For example: 


b.state(['disabled']) # set the disabled flag 
b.state(['!disabled']) # clear the disabled flag 
b.instate(['disabled']) # true if disabled, else false 
b.instate(['!disabled']) # true if not disabled, else 
false 

b.instate(['!disabled'], cmd) # execute 'cmd' if not 
disabled 


Q Note that these commands accept an array of state flags as their 
argument. 


The full list of state flags available to themed widgets is: active, 
disabled, focus, pressed, selected, background, readonly, alternate, 
and invalid. These are described in the themed widget reference. 
While all widgets have the same set of state flags, not all states are 
meaningful for all widgets. It's also possible to get fancy in the state 
and instate methods and specify multiple state flags at the same 
time. 
[3 https://tkdocs.com/man/ttk_widget 


The state and instate methods replace the older state configuration 
option (which took the values normal OF disabled). 


UPGRADE 
Besestsccbel 


That configuration option is actually still available for themed widgets in Tk 8.5, 
but "write-only," which means that changing the option calls the appropriate 
state command. It's mainly intended as a convenience so you can specify a 
widget should be disabled when you first create it. However, any changes 
made using the new state command do not update the configuration option. To 


avoid confusion, you should update your code to use the new state flags for all 
themed widgets. 


6.4. Checkbutton 


. ttk.Checkbutton 
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A checkbutton widget is like a regular button that also holds a 
binary value of some kind (i.e., a toggle). When pressed, a 
checkbutton flips the toggle and then invokes its callback. 
Checkbutton widgets are frequently used to allow users to turn an 
option on or off. 
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Checkbutton widgets. 


Checkbuttons are created using the ttk.checkbutton Class. Typically, 
their contents and behavior are specified at the same time: 


measureSystem = StringVar () 

check = ttk.Checkbutton(parent, text='Use Metric', 
command=metricChanged, variable=measureSystem, 
onvalue='metric', offvalue='imperial') 


Checkbuttons use many of the same options as regular buttons but 
add a few more. The text, textvariable, image, and compound 
configuration options control the display of the label (next to the 
checkbox itself). Similarly, the commana option lets you specify a 
command to be called every time a user toggles the checkbutton; 
and the invoke method will also execute the same command. The 


state and instate methods allow you to manipulate the disabled 
state flag to enable or disable the checkbutton. 


Widget Value 


Unlike regular buttons, checkbuttons also hold a value. We've seen 
before how the textvariabie option can link the label of a widget to a 
variable in your program. The variable option for checkbuttons 
behaves similarly, except it links a variable to current value of the 
widget. The variable is updated whenever the widget is toggled. By 
default, checkbuttons use a value of 1 when the widget is checked, 
and o when not checked. These can be changed to something else 
using the onvalue and offvalue options. 

A checkbutton doesn't automatically set (or create) the linked 
variable. Therefore, your program needs to initialize it to the 
appropriate starting value. 

What happens when the linked variable contains neither the 
onvalue Or the offvalue (or even doesn't exist)? In that case, the 
checkbutton is put into a special "tristate" or indeterminate mode. 
When in this mode, the checkbox might display a single dash, 
instead of being empty or holding a checkmark. Internally, the state 
flag alternate is set, which you can inspect via the instate method: 


check.instate(['alternate']) 


While we've been using an instance of the stringvar class, Tkinter 
provides other variable classes that can hold booleans, integers, or 
floating-point numbers. You can always use a stringvar (because 
the Tcl API that Tkinter uses is string-based) but can choose one of 
the others if the data that will be stored in it fits the type. All are 
subclasses of the base class variable. 

We saw in the feet to meters example that you can call the get 
method of a variable to retrieve its value or the set method to 
provide a new value. You can also supply an initial value when you 
instantiate it. 


Aron 


= StringVar (value="abc") 
= BooleanVar (value=True) 
= IntVar (value=10) 

= DoubleVar (value=10.5) 


# default 
# default 
# default 
# default 


value is 
is False 
is 0 

is 0.0 


' 


' 


6.5. Radiobutton 


nel ttk.Radiobutton 
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A radiobutton widget lets you choose between one of several 
mutually exclusive choices. Unlike a checkbutton, they are not 
limited to just two options. Radiobuttons are always used together in 
a set, where multiple radiobutton widgets are tied to a single choice 
or preference. They are appropriate to use when the number of 
options is relatively small, e.g., 3-5. 
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Radiobutton widgets. 


Radiobuttons are created using the ttk.Radiobutton Class. Typically, 
you'll create and initialize several of them at once: 


phone = StringVar () 

home = ttk.Radiobutton(parent, text='Home', variable=phone, 
value='home') 
office = ttk.Radiobutton(parent, text='Office', 
variable=phone, value='office') 

cell = ttk.Radiobutton (parent, text='Mobile', variable=phone, 
value='cell') 


Radiobuttons share most of the same configuration options as 
checkbuttons. One exception is that the onvalue and offvalue 
options are replaced with a single value option. Each radiobutton in 
the set will have the same linked variable, but a different value. 


When the variable holds the matching value, that radiobutton will 
visually indicate it is selected. If it doesn't match, the radiobutton will 
be unselected. If the linked variable doesn't exist, or you don't 
specify one with the variable option, radiobuttons also display as 
"tristate" or indeterminate. This can be checked via the alternate 
state flag. 


6.6. Entry 


MH. ttk. Entry 
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An entry widget presents users with a single line text field where 
they can type in a string value. These can be just about anything: a 
name, a city, a password, social security number, etc. 
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Entry widgets. 
Entries are created using the ttk.Entry Class: 
username = StringVar () 
name = ttk.Entry(parent, textvariable=username) 


A width configuration option may be specified to provide the number 
of characters wide the entry should be. This allows you, for example, 
to display a shorter entry for a zip or postal code. 


Entry Contents 


We've seen how checkbutton and radiobutton widgets have a value 
associated with them. Entries do as well, and that value is usually 
accessed through a linked variable specified by the textvariable 
configuration option. 


Unlike the various buttons, entries don't have a text or image beside 
Q them to identify them. Use a separate label widget for that. 


You can also get or change the value of the entry widget 
without going through the linked variable. The get method returns 
the current value, and the delete and insert methods let you change 
the contents, e.g. 


QO 


print ('current value is %s' % name.get()) 


name.delete(0,'end') # delete between two indices, 
0 -based 

name.insert(0, 'your name') # insert new text at a given 
index 


Watching for Changes 


Entry widgets don't have a command option to invoke a callback 
whenever the entry is changed. To watch for changes, you should 
watch for changes to the linked variable. See also "Validation", 
below. 


def it has been written(*args): 


username.trace add("write", it_has been written) 


You'll be fine if you stick with simple uses of trace add like that 
shown above. You might want to know that this is a small part of a 
much more complex system for observing variables and invoking 
callbacks when they are read, written, or deleted. You can trigger 
multiple callbacks, add or delete them (trace remove), and introspect 
them (trace info). 


These methods also replace a now-deprecated set of older methods (race, 
trace variable, trace vdelete, and trace vinfo) that should not be used. 


UPGRADE 
Pesosrescobks 


Tkinter allows you to watch for changes on a stringVar (or 
any subclass of variable). Both the older and newer tracing tools are 


a very thin (and not terribly Pythonic) front end to Tcl's trace 
command. 
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Passwords 


Entries can be used for passwords, where the actual contents are 
displayed as a bullet or other symbol. To do this, set the show 
configuration option to the character you'd like to display. 


passwd = ttk.Entry(parent, textvariable=password, show="*") 


Widget States 


Like the various buttons, entries can also be put into a disabled state 
via the state command (and queried with instate). Entries can also 
use the state flag readonly; if set, users cannot change the entry, 
though they can still select the text in it (and copy it to the clipboard). 
There is also an invalid State, set if the entry widget fails validation, 
which leads us to... 


Validation 


Users can type any text they like into an entry widget. However, if 
you'd like to restrict what they can type into the entry, you can do so 
with validation. For example, an entry might only accept an integer or 
a valid zip or postal code. 

Your program can specify what makes an entry valid or invalid, as 
well as when to check its validity. As we'll see soon, the two are 
related. We'll start with a simple example, an entry that can only hold 
an integer up to five digits long. 

The validation criteria is specified via an entry's validatecommand 
configuration option. You supply a piece of code whose job is to 
validate the entry. It functions like a widget callback or event binding, 
except that it returns a value (whether or not the entry is valid). We'll 


arrange to validate the entry on any keystroke, which is specified by 
providing a value of key to the validate configuration option. 


import re 
def check _num(newval): 


return re.match('*[0-9]*$', newval) is not None and 
len(newval) <= 5 
check num wrapper = (root.register(check num), '%P"') 
num = StringVar () 
e = ttk.Entry(root, textvariable=num, validate='key', 


validatecommand=check num wrapper) 
e.grid(column=0, row=0, sticky='we') 


https://tkdocs.com/code/numvalidate.py 


A few things are worth noting. First, as with event bindings, we can 
access more information about the conditions that triggered the 
validation via percent substitutions. We used one of these here: sp is 
the new value of the entry /f the validation passes. We'll use a simple 
regular expression and a length check to determine if the change is 
valid. To reject the change, our validation command can return a 
false value, and the entry will remain unchanged. 

Taking advantage of these percent substitutions requires a bit of 
gymnastics. You'll recall that Tkinter abstracts away percent 
substitutions in event binding callbacks. There, all of the event 
parameters are wrapped into an event object which is always passed 
to the callback. There's not an equivalent abstraction for validation 
callbacks. Instead, we have to choose which percent substitutions 
we're interested in. The register method (which can be called on 
any widget, not just root) creates a Tcl procedure which will call our 
Python function. The percent substitutions we've chosen will be 
passed to it as parameters. 

Let's extend our example so that the entry will accept a US zip 
code, formatted as "4H" or "HHAHH-THHH" ("#" can be any digit). 
We'll still do some validation on each keystroke (only allowing entry 
of numbers or a hyphen). However, We can no longer fully validate 
the entry on every keystroke; if they've just typed the first digit, it's 
not valid yet. So full validation will only happen when the entry loses 
focus (e.g., a user tabs away from it). Tk refers to this as 


revalidation, in contrast with prevalidation (accepting changes on 
each keystroke). 

How should we respond to errors? Let's add a message 
reminding users of the format. It will appear if they type a wrong key 
or tab away from the entry when it's not holding a valid zip code. 
We'll remove the message when they return to the entry or type a 
valid key. We'll also add a (dummy) button to "process" the zip code, 
which will be disabled unless the zip entry is valid. Finally, we'll also 
add a "name" entry so you can tab away from the zip entry. 


import re 
errmsg = StringVar () 
formatmsg = "Zip should be ##### OF FHEHH-PHHE" 


def check zip(newval, op): 

errmsg.set('') 

valid = re.match('*[0-9]{5}(\-[0-9]{4})?S', newval) is 
not None 


btn.state(['!disabled'] if valid else ['disabled']) 
if op=='key': 
ok so far = re.match('*[0-9\=-]*$"', newval). is. not 


None and len(newval) <= 10 
Gf NOt ‘Ok. sofas 
errmsg.set (formatmsg) 
return Ok SO rar 
elif op=='focusout!: 
if not valid: 
errmsg.set (formatmsg) 
return valid 
check zip wrapper = (root.register(check Zip), "eR", "sV") 


Zip = StringVar () 
f = ttk.Frame (root) 
f.grid(column=0, row=0) 


ttk.Label(f, text='Name:').grid(column=0, row=0, padx=5, 
pady=5) 

ttk.Entry(f).grid(column=1, row=0, padx=5, pady=5) 
ttk.Label(f, text='Zip:').grid(column=0, row=1, padx=5, 
pady=5) 

e = ttk.Entry(f, textvariable=zip, validate='all', 


validatecommand=check zip wrapper) 
e.grid(column=1, row=1, padx=5, pady=5) 
btn = ttk.Button(f, text="Process") 
btn.grid(column=2, row=1, padx=5, pady=5) 
btn.state(['disabled']) 


msg = ttk.Label(f, font='TkSmallCaptionFont', 
foreground='red', textvariable=errmsg) 
msg.grid(column=1, row=2, padx=5, pady=5, sticky='w') 


https://tkdocs.com/code/validate.py 


Notice that the validate configuration option has been changed from 
key to all. That arranges for the validatecommand Callback to be 
invoked on not only keystrokes but other triggers. The trigger is 
passed to the callback using the sv percent substitution. The 
callback differentiated between key and focusout triggers (you can 
also check for focusin). 


AY. There's a few more things to know about validation. First, if your 
validatecommand ever generates an error (or doesn't return a boolean), 
validation will be disabled for that widget. Your callback can modify the 

entry, e.g., change its textvariable. You can ask the widget to validate at any 
time by calling it's validate method, which returns true if validation passes (the 
sv Substitution is set to forced). 


There iS an invalidcommand configuration option (which works like 
validatecommand) that is called whenever validation fails. You can use it to 
accomplish nasty things like forcing the focus back on the widget that didn't 
validate. In practice, it's rarely used. AS mentioned earlier, the entry's invalid 
state flag (which can be checked via the instate invalid method) is 
automatically updated as validation succeeds or fails. 


Other percent substitutions allow you to get the entry's contents prior to editing 
(=s), differentiate between insert and delete (=a), where an insert or delete 
occurs (zi), what is being inserted or deleted (zs), the current setting of the 
validate option (=v) and the name of the widget (zw). 


6.7. Combobox 


fr ttk .Combobox 
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A combobox widget combines an entry with a list of choices. This 
lets users either choose from a set of values you've provided (e.g., 
typical settings), but also put in their own value (e.g., for less 
common cases). 
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Combobox widgets. 


Comboboxes are created using the ttk.combobox class: 


countryvar = StringVar () 
country = ttk.Combobox (parent, textvariable=countryvar) 


Like entries, the textvariable option links a variable in your program 
to the current value of the combobox. As with other widgets, you 
should initialize the linked variable in your own code. 

A combobox will generate a <<comboboxSelecteda>> virtual event 
that you can bind to whenever its value changes. (You could also 
trace changes on the textvariable, aS we've seen in the previous 
few widgets we covered. Binding to the event is more 
straightforward, and so tends to be our preferred choice.) 


country.bind('<<ComboboxSelected>>', function) 


Predefined Values 


You can provide a list of values that users can choose from using the 
values Configuration option: 


country['values'] = ('USA', 'Canada', 'Australia') 


If set, the readonly state flag will restrict users to making choices 
only from the list of predefined values, but not be able to enter their 
own (though if the current value of the combobox is not in the list, it 
won't be changed). 


country.state(["readonly"] ) 


Q If you're using the combobox in readonly mode, I'd recommend that 
when the value changes (i.€., ON a <<ComboboxSelected>> event), that 
you call the selection clear method. It looks a bit odd visually without 

doing that. 


You can also get the current value using the get method, and change 
the current value using the set method (which takes a single 
argument, the new value). 

As a complement to the get and set methods, you can also use 
the current method to determine which item in the predefined values 
list is selected. Call current with no arguments; it will return a O- 
based index into the list, or -1 if the current value is not in the list. 
You can select an item in the list by calling current with a single O- 
based index argument. 


Want to associate some other value with each item in the list so that 

your program can use one value internally, but it gets displayed in the 

combobox as something else? You'll want to have a look at the section 
entitled "Keeping Extra Item Data" when we get to the discussion of listboxes 
in a couple of chapters from now. 


7. The Grid Geometry Manager 


We'll take a bit of a break from talking about different widgets (what 
to put onscreen) and focus instead on geometry management 
(where to put those widgets). We introduced the general idea of 
geometry management in the "Tk Concepts" chapter. Here, we focus 
on one specific geometry manager: grid. 

As we've seen, grid lets you layout widgets in columns and rows. 
If you're familiar with using HTML tables to do layout, you'll feel right 
at home here. This chapter illustrates the various ways you can 
tweak grid to give you all the control you need for your user 
interface. 

Grid is one of several geometry managers available in Tk, but its 
mix of power, flexibility, and ease of use make it the best choice for 
general use. Its constraint model is a natural fit with today's layouts 
that rely on the alignment of widgets. There are other geometry 
managers in Tk: pack is also quite powerful, but harder to use and 
understand, while piace gives you complete control of positioning 
each element. Even widgets like paned windows, notebooks, 
canvas, and text that we'll explore later can act as geometry 
managers. 


th It's worth noting that gria was first introduced to Tk in 1996, several 


mam years after Tk became popular, and it took a while to catch on. Before 
that, developers had always used pack to do constraint-based 


geometry management. When gria came out, many developers kept using 
pack, and you'll still find it used in many Tk programs and documentation. While 
there's nothing technically wrong with pack, the algorithm's behavior is often 
hard to understand. More importantly, because the order that widgets are 
packed is significant in determining layout, modifying existing layouts can be 
more difficult. Aligning widgets in different parts of the user interface is also 
much trickier. 


Grid has all the power of pack, produces nicer layouts (that align widgets both 
horizontally and vertically), and is easier to learn and use. Because of that, we 
think grid is the right choice for most developers most of the time. Start your 
new programs using grid, and switch old ones to grid as you're making 
changes to an existing user interface. 


The reference documentation for grid provides an exhaustive 
description of grid, its behaviors and all options. 
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7.1. Columns and Rows 


In grid, widgets are assigned a column number and a row number. 
These indicate each widget's position relative to other widgets. All 
widgets in the same column will be above or below each other. 
Those in the same row will be to the left or right of each other. 

Column and row numbers must be positive integers (i.e., 0, 1, 2, 
...). You don't have to start at 0 and can leave gaps in column and 
row numbers (e.g., column 1, 2, 10, 11, 12, 20, 21). This is useful if 
you plan to add more widgets in the middle of the user interface 
later. 

The width of each column will vary depending on the width of the 
widgets contained within the column. Ditto for the height of each row. 
This means when sketching out your user interface and dividing it 
into rows and columns, you don't need to worry about each column 
or row being equal width. 


7.2. Spanning Multiple Cells 


Widgets can take up more than a single cell in the grid; to do this, 
we'll use the columnspan and rowspan options when gridding the 
widget. These are analogous to the "colspan" and "rowspan" 
attribute of HTML tables. 

Here is an example of creating a user interface with multiple 
widgets, some that take up more than a single cell. 


@0e@ Grid Example 


Three Cancel 
Gridding multiple widgets. 


from tkinter import * 
from tkinter import ttk 


root = Tk() 

content = ttk.Frame (root) 

frame = ttk.Frame(content, borderwidth=5, relief="ridge", 
width=200, height=100) 

namelbl = ttk.Label (content, text="Name") 

name = ttk.Entry(content) 

onevar = BooleanVar (value=True) 

twovar = BooleanVar (value=False) 

threevar = BooleanVar (value=True) 

one = ttk.Checkbutton(content, text="One", variable=onevar, 
onvalue=True) 

two = ttk.Checkbutton(content, text="Two", variable=twovar, 
onvalue=True) 

three = ttk.Checkbutton(content, text="Three", 


variable=threevar, onvalue=True) 


ok = ttk.Button(content, text="Okay") 
cancel = ttk.Button(content, text="Cancel") 


content.grid(column=0, row=0) 

frame.grid(column=0, row=0, columnspan=3, rowspan=2) 
namelbl.grid(column=3, row=0, columnspan=2) 
name.grid(column=3, row=1, columnspan=2) 
one.grid(column=0, row=3) 

two.grid(column=1, row=3) 

three.grid(column=2, row=3) 

ok.grid(column=3, row=3) 

cancel.grid(column=4, row=3) 


root.mainloop () 


7.3. Layout within the Cell 


Because the width of a column (and height of a row) depends on all 
the widgets that have been added to it, the odds are that at least 
some widgets will have a smaller width or height than has been 
allocated for the cell its been placed in. So the question becomes, 
where exactly should it be put within the cell? 

By default, if a cell is larger than the widget contained in it, the 
widget will be centered within it, both horizontally and vertically. The 
master's background will display in the empty space around it. In the 
figure below, the widget in the top right is smaller than the cell 
allocated to it. The (white) background of the master fills the rest of 
the cell. 
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Layout within the cell and the ‘sticky’ option. 


The sticky option can change this default behavior. Its value is a 
string of O or more of the compass directions nsew, specifying which 
edges of the cell the widget should be "stuck" to. For example, a 
value of n (north) will jam the widget up against the top side, with any 
extra vertical space on the bottom; the widget will still be centered 
horizontally. A value of nw (north-west) means the widget will be 
stuck to the top left corner, with extra space on the bottom and right. 


Q In Tkinter, you can also specify this as a list containing any of \, s, =, 
and w. It's a stylistic choice, and we'll tend to use the list format in this 
book. 


Specifying two opposite edges, such as we (west, east) means that 
the widget will be stretched. In this case, it will be stuck to both the 


left and right edge of the cell. So the widget will then be wider than 
its "ideal" size. 

If you want the widget to expand to fill up the entire cell, grid it 
with a sticky value of nsew (north, south, east, west), meaning it will 
stick to every side. This is shown in the bottom left widget in the 
above figure. 


Most widgets have options that can control how they are displayed if 

they are larger than needed. For example, a label widget has an anchor 

option that controls where the label's text will be positioned within the 
widget's boundaries. The bottom left label in the figure above uses the default 
anchor (w, i.e., left side, vertically centered). 


If you're having trouble getting things to line up the way you want them to, first 
make sure you know large the widget is. AS we discussed with the label 
widget in the previous chapter, changing the widget's background or border 
can help. the 


7.4. Handling Resize 


If you've tried to resize the example, you'll notice that nothing moves 
at all, as shown below. 


@e0oe Grid Example 


Name 


One Two Three Okay Cancel 


Resizing the window. 


Even if you took a peek below and added the extra sticky options to 
our example, you'd still see the same thing. It looks like sticky may 
tell Tk how to react if the cell's row or column does resize, but 
doesn't actually say that the row or columns should resize if extra 
room becomes available. Let's fix that. 

Every column and row in the grid has a weight option associated 
with it. This tells gria how much the column or row should grow if 
there is extra room in the master to fill. By default, the weight of each 
column or row is 0, meaning it won't expand to fill any extra space. 

For the user interface to resize then, we'll need to specify a 
positive weight to the columns that we'd like to expand. This is done 
using the columnconfigure and rowconfigure methods of GEL. This 
weight is relative. If two columns have the same weight, they'll 
expand at the same rate. In our example, we'll give the three 
leftmost columns (holding the checkbuttons) a weight of 3, and the 
two rightmost columns a weight of 1. For every one pixel the right 
columns grow, the left columns will grow by three pixels. So as the 
window grows larger, most of the extra space will go to the left side. 


@00e Grid Example with Resize 
Name 


One Two Three Okay Cancel 
Resizing the window after adding weights. 


Both columnconfigure aNd rowconfigure also take a minsize grid 
option, which specifies a minimum size which you really don't want 
the column or row to shrink beyond. 


7.5. Padding 


Normally, each column or row will be directly adjacent to the next, so 
that widgets will be right next to each other. This is sometimes what 
you want (think of a listbox and its scrollbar), but often you want 
some space between widgets. In Tk, this is called padding, and there 
are several ways you can choose to add it. 

We've already actually seen one way, and that is using a widget's 
own options to add the extra space around it. Not all widgets have 
this, but one that does is a frame; this is useful because frames are 
most often used as the master to grid other widgets. The frame's 
padding option lets you specify a bit of extra padding inside the 
frame, whether the same amount for each of the four sides or even 
different for each. 

A second way is using the padx and pady grid options when adding 
the widget. As you'd expect, padx puts a bit of extra space to the left 
and right, while pady adds extra space top and bottom. A single 
value for the option puts the same padding on both left and right (or 
top and bottom), while a two-value list lets you put different amounts 
on left and right (or top and bottom). Note that this extra padding is 
within the grid cell containing the widget. 

If you want to add padding around an entire row or column, the 
columnconfigure and rowconfigure methods accept a pad option, 
which will do this for you. 

Let's add the extra sticky, resizing, and padding behavior to our 
example (additions in bold). 


from tkinter import * 
from tkinter import ttk 


root = Tk() 


content = ttk.Frame(root, padding=(3,3,12,12) ) 


frame = ttk.Frame(content, borderwidth=5, relief="ridge", 
width=200, height=100) 

namelbl = ttk.Label (content, text="Name") 

name = ttk.Entry (content) 


onevar = BooleanVar () 
twovar = BooleanVar () 
threevar = BooleanVar() 


onevar.set (True) 
twovar.set (False) 
threevar.set (True) 


one = ttk.Checkbutton(content, text="One", variable=onevar, 
onvalue=True) 

two = ttk.Checkbutton(content, text="Two", variable=twovar, 
onvalue=True) 

three = ttk.Checkbutton(content, text="Three", 
variable=threevar, onvalue=True) 

ok = ttk.Button(content, text="Okay") 

cancel = ttk.Button(content, text="Cancel") 


content.grid(column=0, row=0, sticky=(N, S, E, W)) 
frame.grid(column=0, row=0, columnspan=3, rowspan=2, sticky= 
(N, S, E, W)) 
namelbl.grid(column=3, row=0, columnspan=2, sticky=(N, W), 
padx=5 ) 

name.grid(column=3, row=1, columnspan=2, sticky=(N,E,W), 
pady=5, padx=5) 

one.grid(column=0, row=3) 

two.grid(column=1, row=3) 

three.grid(column=2, row=3) 

ok.grid(column=3, row=3) 

cancel.grid(column=4, row=3) 


root.columnconfigure(0, weight=1) 
root.rowconfigure(0, weight=1) 
content.columnconfigure(0, weight=3) 
content.columnconfigure(1, weight=3) 
content.columnconfigure(2, weight=3) 
content.columnconfigure(3, weight=1) 
content.columnconfigure(4, weight=1) 
content.rowconfigure(1, weight=1) 


root.mainloop() 


This looks more promising. Play around with the example to get a 
feel for the resize behavior. 


@0ce Grid Example Complete 


@ One "| Two @ Three Okay =—s Cancel 


Grid example, handling in-cell layout and resize. 


7.6. Additional Grid Features 


If you look at the reference documentation for gria, you'll see many 
other things you can do with grid. Here are a few of the more useful 
ones. 


[3 https://tkdocs.com/man/grid 


Querying and Changing Grid Options 


Like widgets themselves, it's easy to introspect the various grid 
options or change them. Setting options when you first grid the 
widget is certainly convenient, but you can change them anytime 
you'd like. 

The slaves method will tell you all the widgets that have been 
gridded inside a master, or optionally those within just a certain 
column or row. The info method will return a list of all the grid 
options for a widget and their values. Finally, the configure method 
lets you change one or more grid options on a widget. 

These are illustrated in this interactive session: 


veo Sonlent.grid slaves() 

[<tkinter.ttk.Button object .!frame.!button2>, 
<tkinter.ttk.Button object .!frame.!button>, 
<tkinter.ttk.Checkbutton object .!frame.!checkbutton3>, 
<tkinter.ttk.Checkbutton object .!frame.!checkbutton2>, 
<tkinter.ttk.Checkbutton object .!frame.!checkbutton>, 
<tkinter.ttk.Entry object .!frame.!entry>, 

<tkinter.ttk.Label object .!frame.!label>, <tkinter.ttk.Frame 
object .!frame.!frame>] 

Jor 168 W In-Content grid. Slaves ()s print. (w) 


.!frame.!button2 
.!frame.!button 
.!frame.!checkbutton3 
.!frame.!checkbutton2 
.!frame.!checkbutton 
.!'!frame.!entry 
.!frame.!label 
.!'frame.!frame 


eo> Tor Win. content.grid. slaves (row=3) > print (w) 

.!frame.!button2 

.!frame.!button 

.!'!frame.!checkbutton3 

.!frame.!checkbutton2 

.!frame.!checkbutton 

>>> for w in content.grid_ slaves (column=0): print (w) 

.!frame.!checkbutton 

.!frame.!frame 

>>> namelbl.grid_info() 

{'in': <tkinter.ttk.Frame object .!frame>, 'column': 3, 

‘row': O, 'columnspan': 2, 'rowspan': 1, 

‘ipadx': 0, 'ipady': 0, 'padx': 5, 'pady': 0, 'sticky': 'nw'} 

eer mamelbl. grid. contigure (sticky=(E,W) } 

>o> namelbl grid info () 

{'in': <tkinter.ttk.Frame object .!frame>, 'column': 3, 

‘row': O, 'columnspan': 2, 'rowspan': 1, 

‘ipadx': 0, 'ipady': 0, 'padx': 5, 'pady': 0, 'sticky': ‘'ew'} 
Internal Padding 


You saw how the padx and pady grid options added extra space 
around the outside of a widget. There's also a less used type of 
padding called "internal padding" controlled by the grid options ipadx 
and ipady. 

The difference can be subtle. Let's say you have a frame that's 
20x20, and specify normal (external) padding of 5 pixels on each 
side. The frame will request a 20x20 rectangle (its natural size) from 
the geometry manager. Normally, that's what it will be granted, so it'll 
get a 20x20 rectangle for the frame, surrounded by a 5-pixel border. 

With internal padding, the geometry manager will effectively add 
the extra padding to the widget when figuring out its natural size, as 
if the widget has requested a 30x30 rectangle. If the frame is 
centered, or attached to a single side or corner (using sticky), we'll 
end up with a 20x20 frame with extra space around it. If, however, 
the frame is set to stretch (i.e., a sticky value Of we, ns, OF nwes), it 
will fill the extra space, resulting in a 30x30 frame, with no border. 


Forget and Remove 


The forget method of grid removes slaves from the grid they're 
currently part of. It takes a list of one or more slave widgets as 
arguments. This does not destroy the widget altogether but takes it 
off the screen as if it had not been gridded in the first place. You can 
grid it again later, though any grid options you'd originally assigned 
will have been lost. 

The remove method of grid works the same, except that the grid 
options will be remembered if you gria it again later. 


7.7. Nested Layouts 


As your user interface gets more complicated, the grid that you're 
using to organize all your widgets can get increasingly complicated. 
This can make changing and maintaining your program very difficult. 

Luckily, you don't have to manage your entire user interface with a 
single grid. If you have one area of your user interface that is fairly 
independent of others, create a new frame to hold that area and grid 
the widgets in area within that frame. For example, if you were 
building a graphics editor with multiple palettes, toolbars, etc., each 
one of those areas might be a candidate for putting in its own frame. 

In theory, these frames, each with its own grid, can be nested 
arbitrarily deep, though, in practice, this usually doesn't go beyond a 
few levels. This can be a big help in modularizing your program. If, 
for example, you have a palette of drawing tools, you can create the 
whole thing in a separate function or class. It would be responsible 
for creating all the component widgets, gridding them together, 
setting up event bindings, etc. The details of how things work inside 
that palette can be contained in that one piece of code. From the 
point of view of your main program, all it needs to Know about is the 
single frame widget containing your palette. 

Our examples have shown just a hint of this, where a content 
frame was gridded into the main window, and then all the other 
widgets gridded into the content frame. 

As your own programs grow larger, you'll likely run into situations 
where making a change in the layout of one part of your interface 
requires code changes to the layout of another part. That may be a 
clue to reconsider how you're using gria and if splitting out 
components into separate frames would help. 


8. More Widgets 


This chapter carries on introducing several more widgets: listbox, 
scrollbar, text, scale, spinbox, and progressbar. Some of these are 
starting to be a bit more powerful than the basic ones we looked at 
before. Here we'll also see a few instances of using the classic Tk 
widgets, in cases where there isn't (or there isn't a need for) a 
themed counterpart. 


8.1. Listbox 


ae Listbox 


[3 https://tkdocs.com/man/listbox 


A listbox widget displays a list of single-line text items, usually 
lengthy, and allows users to browse through the list, selecting one or 
more. 

Listboxes are part of the classic Tk widgets; there is not presently 
a listbox in the themed Tk widget set. 


Q Tk's treeview widget (which is themed) can also be used as a listbox (a 
one level deep tree), allowing you to use icons and styles with the list. 
It's also likely that a multi-column (table) list widget will make it into Tk 

at some point, whether based on treeview or one of the available extensions. 


macOS Windows Linux 

Tel Tcl 
Ruby Ruby 
Python 
Perl Perl 
Lua 

Lua 
Lisp : 
Caml Lisp 
Erlang Caml 

Erlang 
Listbox widgets. 


Listboxes are created using the Listbox class. A height configuration 
option can specify the number of lines the listbox will display at a 
time without scrolling: 


1 = Listbox(parent, height=10) 


Populating the Listbox Items 


There's an easy way and a hard way to populate and manage all the 
items in the listbox. 

Here's the easy way. Each listbox has a listvariable 
configuration option, which allows you to link a variable (which must 
hold a list) to the listbox. Each element of this list is a string 
representing one item in the listbox. To add, remove, or rearrange 
items in the listbox, you can simply modify this variable as you would 
any other list. Similarly, to find out, e.g., which item is on the third line 
of the listbox, just look at the third element of the list variable. 

It's actually not quite that easy. Tkinter doesn't allow you to link 
regular Python lists to a listbox. AS we saw with widgets like entry, 
we need to use a Stringvar as an intermediary. It provides a 
mapping between Python's lists and a string representation that the 
underlying Tk widgets can use. It also means that anytime we 
change the list, we need to update the stringvar. 


choices = ["apple", "orange", "banana"] 
choicesvar = StringVar (value=choices) 
1 = Listbox(parent, listvariable=choicesvar) 


choices.append ("peach") 
choicesvar.set (choices) 


The older, harder way to do things is to use a set of methods that are 
part of the listbox widget itself. They operate on the (internal) list of 
items maintained by the widget: 


e The insert idx item ?item...? method is used to add one or 
more items to the list; iax is a O-based index indicating the 
position of the item before which the item(s) should be added; 
specify end to put the new items at the end of the list. 


e Use the delete first ?last? method to delete one or more 
items from the list; first and last are indices as per the insert 
method. 


e Use the get first ?last? method to return the contents of a 
single item at the given position, or a list of the items between 
first and last. 


e The size method returns the number of items in the list. 


The reason there is a hard way at all is because the listvariable 
option was only introduced in Tk 8.3. Before that, you were stuck with 
the hard way. Because using the list variable lets you use all the 
standard list operations, it provides a much simpler API. It's certainly an 
upgrade worth considering if you have listboxes doing things the older way. 


UPGRADE 


Selecting Items 


You can choose whether users can select only a single item at a time 
from the listbox, or if multiple items can simultaneously be selected. 
This is controlled by the selectmode option: the default is only being 
able to select a single item (browse), while a selectmode Of extended 
allows users to select multiple items. 


truly awful. This is made worse by the fact that there are two other 

modes, single and multiple, which you should not use (they use an 

old interaction style that is inconsistent with modern user interface and 
platform conventions). 


@ namMeS browse and extended, again for backward compatibility reasons, are 


To find out which item or items in the listbox are currently selected, 
use the curselection method. It returns a list of indices of all items 
currently selected; this may be an empty list. For lists with a 
selectmode Of browse, it will never be longer than one item. You can 
also use the Selection ancludes 2ndex method to check if the item 
with the given index is currently selected. 


if bon. selection includes (2): 


To programmatically change the selection, you can use the 
selection clear first ?last? method to deselect either a single 
item or any within the range of indices specified. To select an item or 
all items in a range, use the Selection set i278 riast? method. 
Both of these will not touch the selection of any items outside the 
range specified. 


If you change the selection, you should also make sure that the 
newly selected item is visible (i.e., it is not scrolled out of view). To 
do this, use the see index method. 


lboxuselection set (idx) 
lbox.see (idx) 


When a user changes the selection, a <<ListboxSelect>> virtual 
event is generated. You can bind to this to take any action you need. 
Depending on your application, you may also want to bind to a 
double-click <Double-1> event and use it to invoke an action with the 
currently selected item. 


lbox.bind("<<ListboxSelect>>", lambda e: 
updateDetails (lbox.curselection())) 
lbox.bind("<Double-1>", lambda e: 
invokeAction (lbox.curselection())) 


Stylizing the List 


Like most of the "classic" Tk widgets, you have immense flexibility in 
modifying the appearance of a listbox. As described in the reference 
manual, you can modify the font the listbox items are displayed in, 
the foreground (text) and background colors for items in their normal 
state, when selected, when the widget is disabled, etc. There is also 
an itemconfigure method that allows you to change the foreground 
and background colors of individual items. 

As is often the case, restraint is useful. Generally, the default 
values will be entirely suitable and a good match for platform 
conventions. In the example we'll get to momentarily, we'll show how 
restrained use of these options can be put to good effect, in this case 
displaying alternate lines of the listbox in slightly different colors. 


Keeping Extra Item Data 


The listvariable (or the internal list, if you're managing things the 
old way) holds the strings that will be shown in the listbox. It's often 
the case, though, that each string you're displaying is associated 


with some other data item. This might bean internal object that is 
meaningful to your program, but not meant to be displayed to users. 
In other words, what you're really interested in is not so much the 
string displayed in the listbox, but the associated data item. For 
example, a listbox may display a list of names to users, but your 
program is really interested in the underlying user object (or id 
number) for each one, not the particular name. 

How can we associate this underlying value with the name that is 
displayed? Unfortunately, the listbox widget itself doesn't offer any 
facilities, so it's something we'll have to manage separately. There 
are a couple of obvious approaches. First, if the displayed strings are 
guaranteed unique, you could use a hash table to map each name to 
its associated underlying object. This wouldn't work well for peoples’ 
names, where duplicates are possible, but could work for countries, 
which are unique. 

A second approach is to keep a second list, parallel to the list of 
strings displayed in the listbox. This second list will hold the 
underlying object associated with each item that is displayed. So the 
first item in the displayed strings list corresponds to the first item in 
the underlying objects list, the second to the second, etc. Any 
changes that you make in one list (insert, delete, reorder), you must 
make in the other. You can then easily map from the displayed list 
item to the underlying object, based on their position in the list. 


Example 


Here is a silly example showing several of these listbox techniques. 
We'll have a list of countries displayed. We'll be able to select only a 
single country at a time. As we do so, a status bar will display the 
population of the country. You can press a button to send one of 
several gifts to the selected country's head of state (well, not really, 
but use your imagination). Sending a gift can also be triggered by 
double-clicking the list or hitting the Return key. 

Behind the scenes, we maintain two lists in parallel. The first is a 
list of two-letter country codes. The other is the corresponding name 
for each country that we will display in the listbox. We also have a 


simple hash table that contains the population of each country, 
indexed by the two-letter country code. 


wv Country ar O x 
Belgium Send to country's leader: 

‘Brazil 

SE © Greeting card 

China O Flowers 

Denmark 

Finland = 

France Send Gift 
(Greece 

india Sent Nastygram to leader of Canada 
Italy 


The population of Canada (ca) is 33148682 
Country selector listbox example. 


from tkinter import 
from tkinter import 
root = Tk() 


ct ct 


ttk 


# Initialize our country "databases": 
# - the list of country codes (a subset anyway) 
# - parallel list of country names, same order as the 
country codes 
# - a hash table mapping country code to population 
countrycodes = ('ar', ‘au', '‘be', 'br', 'ca', ‘'cn', 'dk', 
teas ‘fet, het» tian y te aay ae "mx', twit y hn tes’, 
‘ge’, ‘ch') 
countrynames = ('Argentina', ‘Australia', 'Belgium', 
"Brazil', 'Canada', 'China', 'Denmark', \ 
'"Finland', 'France', 'Greece', 'India', ‘'Italy', 
'Japan', 'Mexico', 'Netherlands', 'Norway', 'Spain', \ 
"Sweden', 'Switzerland') 
cnames = StringVar (value=countrynames) 
populations = {'ar':41000000, ‘au':21179211, 'be':10584534, 
ibe’ se SoTL S27, %\ 
"ca':33148682, 'cn':1323128240, 'dk':5457415, 
Tei" s5S02000, "se" 52102100, or ellie ood, * 
Yin':1131043000, 'it':59206382, 'jp':127718000, 
"mx ’ s106535000, ‘nl'rle402414, \ 
™no':4738085, 'es':45116894, 'se':9174082, 
"ch':7508 700} 


# Names of the gifts we can send 


gifts = { 'card':'Greeting card', 'flowers':'Flowers', 
"nastygram': 'Nastygram' } 


# State variables 

gift = StringVar () 
sentmsg = StringVar () 
statusmsg = StringVar () 


# Called when the selection in the listbox changes; figure 
out 
# which country is currently selected, and then lookup its 
country 
# code, and from that, its population. Update the status 
message 
# with the new population. As well, clear the message about 
the 
# gift being sent, so it doesn't stick around after we start 
doing 
# other things. 
def showPopulation(*args): 
idxs = lbox.curselection () 
if len(idxs) == 
idx = int (idxs[0]) 
code = countrycodes [idx] 
name = countrynames [idx] 
popn = populations [code] 
statusmsg.set("The population of Ss (%S) is Sd" &% 
(name, code, popn) ) 
sentmsg.set('') 


# Called when the user double clicks an item in the listbox, 
presses 
# the "Send Gift" button, or presses the Return key. In case 
the selected 
# item is scrolled out of view, make sure it is visible. 
7 
# Figure out which country is selected, which gift is 
selected with the 
# radiobuttons, "send the gift", and provide feedback that it 
was sent. 
def sendGift(*args): 
idxs = lbox.curselection() 
if len(idxs) == 
idx = int (idxs[0]) 
lbox.see (idx) 
name = countrynames [idx] 
# Gift sending left as an exercise to the reader 


QO 


sentmsg.set("Sent s to leader of %s" % 


(gifts[gift.get()], name) ) 


# Create and grid the outer content frame 
c = ttk.Frame(root, padding=(5, 5, 12, 0)) 
c.grid(column=0, row=0, sticky=(N,W,E,S) ) 
root.grid_ columnconfigure(0, weight=1) 
root.grid rowconfigure (0,weight=1) 


# Create the different widgets; note the variables that many 
# of them are bound to, as well as the button callback. 
# We're using the StringVar() 'cnames', constructed from 


"countrynames' 

lbox = Listbox(c, listvariable=cnames, height=5) 

lbl = ttk.Label(c, text="Send to country's leader:") 

gl = ttk.Radiobutton(c, text=gifts['card'], variable=gift, 
value='card') 

g2 = ttk.Radiobutton(c, text=gifts['flowers'], variable=gift, 
value='flowers') 

g3 = ttk.Radiobutton(c, text=gifts['nastygram'], 
variable=gift, value='nastygram') 

send = ttk.Button(c, text='Send Gift', command=sendGift, 
default='active') 

sentlbl = ttk.Label(c, textvariable=sentmsg, anchor='center') 
status = ttk.Label(c, textvariable=statusmsg, anchor=W) 


# Grid all the widgets 

lbox.grid(column=0, row=0, rowspan=6, sticky=(N,S,E,W) ) 
lbl.grid(column=1, row=0, padx=10, pady=5) 
gl.grid(column=1, row=1, sticky=W, padx=20) 
g2.grid(column=1, row=2, sticky=W, padx=20) 
g3.grid(column=1, row=3, sticky=W, padx=20) 
send.grid(column=2, row=4, sticky=E) 
sentlbl.grid(column=1, row=5, columnspan=2, sticky=N, pady=5, 
padx=5) 

status.grid(column=0, row=6, columnspan=2, sticky=(W,E) ) 
c.grid_ columnconfigure(0, weight=1) 

c.grid rowconfigure(5, weight=1) 


# Set event bindings for when the selection in the listbox 
changes, 

# when the user double clicks the list, and when they hit the 
Return key 

lbox.bind('<<ListboxSelect>>', showPopulation) 
lbox.bind('<Double-1>', sendGift) 

root.bind('<Return>', sendGift) 


# Colorize alternating lines of the listbox 
for i in range(0,len(countrynames) ,2): 


lbox.itemconfigure(i, background='#f0f0ff"') 


# Set the starting state of the interface, including 
selecting the 

# default gift to send, and clearing the messages. Select 
the first 

# country in the list; because the <<ListboxSelect>> event is 
only 

# fired when users makes a change, we explicitly call 
showPopulation. 

gift.set('card') 

sentmsg.set('') 

statusmsg.set('') 

lbox. selection set (0) 

showPopulation () 


root.mainloop() 


https://tkdocs.com/code/country.py 


One obvious thing missing from this example was that while the list 
of countries could be quite long, only part of it fits on the screen at 
once. To show countries further down in the list, you had to either 
drag with your mouse or use the down arrow key. A scrollbar would 
have been nice. Let's fix that. 


8.2. Scrollbar 


fh. ttk.Scrollbar 


[3 https://tkdocs.com/man/ttk_scrollbar 


A scrollbar widget helps users see all parts of another widget, 
whose content is typically much larger than what can be shown in 
the available screen space. 


macOS Windows Linux 


E 


Scrollbar widgets. 


Scrollbars are created using the ttk.Scrollbar class: 


s = ttk.Scrollbar( parent, orient=VERTICAL, 
command=listbox.yview) 
listbox.configure (yscrollcommand=s.set) 


Unlike in some user interface toolkits, Tk scrollbars are not a part of 
another widget (e.g., a listbox), but are a separate widget altogether. 
Instead, scrollbars communicate with the scrolled widget by calling 
methods on the scrolled widget; as it turns out, the scrolled widget 
also needs to call methods on the scrollbar. 


AX. If you're using a recent Linux distribution, you've probably noticed that 
the scrollbars you see in many applications have changed to look more 


like what you'd see on macOS. This newer look isn't supported on Linux by any 
of the default themes included with Tk. However, some third-party themes do 
support it. 


The orient configuration option determines whether the scrollbar will 
scroll the scrolled widget in the horizontal Of vertical dimension. 
You then need to use the commana configuration option to specify how 
to communicate with the scrolled widget. This is the method to call 
on the scrolled widget when the scrollbar moves. 

Every widget that can be scrolled vertically includes a method 
named yview, while those that can be scrolled horizontally have a 
method named xview). As long as this method is present, the 
scrollbar doesn't need to know anything else about the scrolled 
widget. When the scrollbar is manipulated, it appends several 
parameters to the method call, indicating how it was scrolled, to what 
position, etc. 

The scrolled widget also needs to communicate back to the 
scrollbar, telling it what percentage of the entire content area is now 
visible. Besides the yview and/or xview methods, every scrollable 
widget also. haS a= yscrollcommand and/or = xscrollcommand 
configuration option. This is used to specify a method call, which 
must be the scrollbar's set method. Again, additional parameters will 
be automatically tacked onto the method call. 


Q If, for some reason, you want to move the scrollbar to a particular 
position from within your program, you can call the set first last 
method yourself. Pass it two floating-point values (between O and 1) 

indicating the start and end percentage of the content area that is visible. 


Example 


Listboxes are one of several types of widgets that are scrollable. 
Here, we'll build a very simple user interface, consisting of a 
vertically scrollable listbox that takes up the entire window, with just a 
status line at the bottom. 


Scrolling — 


Line 19 of 100 
Line 20 of 100 
Line 21 of 100 
Line 22 of 100 
|Line 23 of 100 
|Line 24 of 100 
Line 25 of 100 
Line 26 of 100 
|Line 27 of 100 


|Limnn 20 anf Inn 


‘Status message here 
Scrolling a listbox. 


from tkinter import * 
from tkinter import ttk 


root = Tk() 
1 = Listbox(root, height=5) 
l.grid(column=0, row=0, sticky=(N,W,E,S) ) 
s = ttk.Scrollbar (root, orient=VERTICAL, command=1.yview) 
s.grid(column=1, row=0, sticky=(N,S) ) 
1[' yscrollcommand'] = s.set 
ttk.Label (root, text="Status message here", anchor= 
(W)).grid(column=0, columnspan=2, row=1, sticky=(W,E) ) 
root.grid_columnconfigure(0, weight=1) 
root.grid_ rowconfigure(0, weight=1) 
for i in range(1,101): 

l.insert('end', 'Line Sd of 100' % i) 
root.mainloop () 


https://tkdocs.com/code/scrollbar.py 


ey If you've seen an earlier version of this book, you might recall that at 
‘mmm — this point we introduced a sizegrip widget. It placed a small handle at 

the bottom right of the window, allowing users to resize the window by 
dragging the handle. This was commonly seen on some platforms, including 
older versions of macOS. Some older versions of Tk even automatically added 
this handle to the window for you. 


Platform conventions tend to evolve faster than long-lived open source GUI 
toolkits. Mac OS X 10.7 did away with the size grip in the corner, in favor of 
allowing resizing from any window edge, finally catching up with the rest of the 


world. Unless there's a pressing need to be visually compatible with 10+ year 
old operating systems, if you have a sizegrip (class ttk.Sizegrip) in your 
application, it's probably best to remove it. 


8.3. Text 
paat Text 


aa 


[3 https://tkdocs.com/man/text 
A text widget provides users with an area so that they can enter 


multiple lines of text. Text widgets are part of the classic Tk widgets, 
not the themed Tk widgets. 


macOS Windows Linux 


Lorem ipsum dolor 
sit amet, donec a 
dignissimos orci 


Lorem ipsum dolor 

Sit amet, donec a 
dignissimos orci j i ‘| i 

non, nonummy —_ are dignissimos orci 

tristique sit metus, ee non, nonummy 

velit odio at odio tristique sit metus, tristique sit metus, 


 iaanccndihadaaecdicenaiihanacd velit odio at odio 


Text widgets. 


XL. Tk's text widget is, along with the canvas widget, one of two uber- 
powerful widgets that provide amazingly deep but easily programmed 
features. Text widgets have formed the basis for full word processors, 

outliners, web browsers, and more. We'll get into some of the advanced stuff in 
a later chapter. Here, we'll show you how to use the text widget to capture fairly 
simple, multi-line text input. 


Text widgets are created using the Text class: 


t = Text (parent, width=40, height=10) 


The width and height options specify the requested screen size of 
the text widget, in characters and rows, respectively. The contents of 
the text can be arbitrarily large. You can use the wrap configuration 
option to control how line wrapping is handled: values are none (no 


wrapping, text may horizontally scroll), char (wrap at any character), 
and word (wrapping will only occur at word boundaries). 

A text widget can be disabled so that no editing can occur. 
Because text is not a themed widget, the usual state and instate 
methods are not available. Instead, use the configuration option 
state, setting it to either disabled OF normal. 


txt['state'] = 'disabled' 


Scrolling works the same way as in listboxes. The xscrollcommand 
and yscrollcommana configuration options attach the text widget to 
horizontal and/or vertical scrollbars, and the xview and yview 
methods are called from scrollbars. To ensure that a given line is 
visible (i.e., not scrolled out of view), you can use the see index 
method, where index is in the form linenum. charnum, @.g., 5.0 for the 
first (0O-based) character of line 5 (1-based). 


Contents 


Text widgets do not have a linked variable associated with them like, 
for example, entry widgets do. To retrieve the contents of the entire 
text widget, call the method get 1.0 end; the 1.0 is an index into the 
text, and means the first character of the first line, and end is a 
shortcut for the index of the last character in the last line. Other 
indices could be provided to retrieve smaller ranges of text if needed. 


contents = txt.get('1.0', 'end') 


Text can be added to the widget using the insert index string 
method; again index is in the form iine.char and marks the 
character before which text is inserted; use ena to add text to the end 
of the widget. You can delete a range of text using the delete start 
end method, where both start and end are text indices as already 
described. 

We'll get into the text widget's many additional advanced features 
in a later chapter. 


8.4. Scale 


fr ttk.Scale 
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A scale widget allows users to choose a numeric value through 
direct manipulation. 


macOS Windows Linux 


g mencall 


bs eal 


Scale widgets. 


Scale widgets are created using the ttk.Scale Class: 


s = ttk.Scale(parent, orient=HORIZONTAL, length=200, 
Prom =—L.0, to=100 20) 


Q Because ‘from' is a reserved keyword in Python, we need to add a 
trailing underscore when using it as a configuration option. 


The orient option may be either horizontal OF vertical. The length 
option, which represents the longer axis of either horizontal or 
vertical scales, is specified in screen units (e.g., pixels). You should 
also define the range of the number that the scale allows users to 


choose; to do this, set a floating-point number for each of the from_ 
and to configuration options. 

There are several different ways you can set the current value of 
the scale (which must be a floating-point value between the from_ 
and to values). You can set (or read, to get the current value) the 
scale's value configuration option. You can link the scale to a 
variable using the variable option. Or, you can call the scale's set 
value method to change the value, or the get method to read the 
current value. 

A command configuration option lets you specify a script to call 
whenever the scale is changed. Tk will append the current value of 
the scale as a parameter each time it calls this script (we saw a 
similar thing with extra parameters being added to scrollbar 
callbacks). 


# label tied to the same variable as the scale, so auto- 
updates 

num = StringVar () 

ttk.Label (root, textvariable=num) .grid(column=0, row=0, 
sticky='we') 


# label that we'll manually update via the scale's command 
callback 

manual = ttk.Label (root) 

manual.grid(column=0, row=1, sticky='we') 


aeft update Ibl (val): 
manual['text'] = "Scale at "+ val 


scale = ttk.Scale(root, orient='horizontal', length=200, 
from =1.0, to=100.0, variable=num, command=update_1b1) 
scale.grid(column=0, row=2, sticky='we') 

scale.set (20) 


https://tkdocs.com/code/scale.py. 


As with other themed widgets, you can use the state disabled, 
state !disabled, and instate disabled methods to prevent users 
from modifying the scale. 


Q As the scale widget does not display the actual values, you may want 
to add those separately, e.g., using label widgets. 


8.5. Spinbox 


EPL ct. Spinbox 
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A spinbox widget allows users to choose numbers (or, in fact, items 
from an arbitrary list). It does this by combining an entry-like widget 
showing the current value with a pair of small up/down arrows, which 
can be used to step through the range of possible choices. 


Q The themed spinbox was added in Tk 8.5.9 (released in 2010). If you 
must run an older version, there is a spinbox in the classic Tk widgets, 
though with a slightly different API. 


macOS Windows Linux 
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Spinbox widgets. 


Spinbox widgets are created using the ttk.spinbox class: 


spinval = StringVar () 
Ss = ttk.Spinbox(parent, from _=1.0, to=100.0, 
textvariable=spinval) 


Like scale widgets, spinboxes let user choose a number between a 
certain range (specified using the from and to configuration 
options), though through a very different user interface. You can also 
specify an increment, which controls how much the value changes 
every time you click the up or down button. 


Like a listbox or combobox, spinboxes can also be used to let 
users choose an item from an arbitrary list of strings; these can be 
specified using the values configuration option. This works in the 
same way it does for comboboxes; specifying a list of values will 
override to from_ and to settings. 

In their default state, spinboxes allow users to select values either 
via the up and down buttons, or by typing them directly into the entry 
area that displays the current value. If you'd like to disable the latter 
feature, so that only the up and down buttons are available, you can 
set the readonly state flag. 


s.state(['readonly'"]) 


Like other themed widgets, you can also disable spinboxes, via the 
disabled State flag, or check the state via the instate method. 
Spinboxes also support validation in the same manner as entry 
widgets, using the validate and validatecommand configuration 
options. 


Q You might be puzzled about when to choose a scale, listbox, 
combobox, entry, or a spinbox. Often, several of these can be used for 
the same types of data. The answer really depends on what you want 

users to select, platform user interface conventions, and the role the value 

plays in your user interface. 


For example, both a combobox and a spinbox take up fairly small amounts of 
space compared with a listbox. They might make sense for a more peripheral 
setting. A more primary and prominent choice in a user interface may warrant 
the extra space a listbox occupies. Spinboxes don't make much sense when 
items don't have a natural and obvious ordering to them. Be careful about 
putting too many items in both comboboxes and spinboxes. This can make it 
more time consuming to select an item. 


There is a boolean wrap option that determines whether the value 
should wrap around when it goes beyond the starting or ending 
values. You can also specify a width for the entry holding the current 
value of the spinbox. 

Again there are choices as to how to set or get the current value 
in the spinbox. Normally, you would specify a linked variable with the 


textvariable configuration option. As usual, any changes to the 
variable are reflected in the spinbox, while any changes in the 
spinbox are reflected in the linked variable. As well, the set value 
and get methods allow you to set or get the value directly. 

Spinboxes generate virtual events when users press up 
(<<Increment>>) Or down (<<Decrement>>). A command configuration 
option allows you to provide a callback that is invoked on any 
changes. 


8.6. Progressbar 
Mm ttk.Progressbar 
[3 https://tkdocs.com/man/ttk_progressbar 


A progressbar widget provides feedback to users about the 
progress of a lengthy operation. 

In situations where you can estimate how long the operation will 
take to complete, you can display what fraction has already been 
completed. Otherwise, you can indicate the operation is continuing, 
but without suggesting how much longer it will take. 


macOS Windows Linux 
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Progressbar widgets. 


Progressbar widgets are created using the ttk.Progressbar Class: 


p = ttk.Progressbar (parent, orient=HORIZONTAL, length=200, 
mode='determinate') 


As with scale widgets, they should be given an_ orientation 
(horizontal OF vertical) with the orient configuration option, and 
can be given an optional iength. The mode configuration option can 
be set to either determinate, where the progressbar will indicate 
relative progress towards completion, or to indeterminate, where it 


shows that the operation is still continuing but without showing 
relative progress. 


Determinate Progress 


To use determinate mode, estimate the total number of "steps" the 
operation will take to complete. This could be an amount of time but 
doesn't need to be. Provide this to the progressbar using the maximum 
configuration option. It should be a floating-point number and 
defaults to 100.0 (i.e., each step is 1%). 

As you proceed through the operation, tell the progressbar how 
far along you are with the value configuration option. So this would 
start at 0, and then count upwards to the maximum value you have 
set. 


fYZ ‘There are two slight variations on this. First, you can just store the 
current value for the progressbar in a variable linked to it by the 
progressbar'’s variabie configuration option; that way, when you 
change the variable, the progressbar will update. The other alternative is to call 
the progressbar's step ?amount? method. This increments the value by the 
given amount (defaults to 1.0). 


Indeterminate Progress 


Use indeterminate mode when you can't easily estimate how far 
along in a long-running task you actually are. However, you still want 
to provide feedback that the operation is continuing (and that your 
program hasn't crashed). At the start of the operation you'll just call 
the progressbar's start method. At the end of the operation, call its 
stop method. The progressbar will take care of the rest. 

Unfortunately, "the progressbar will take care of the rest" isn't 
quite so simple. In fact, if you start the progressbar, call a function 
that takes several minutes to complete, and then stop the 
progressbar, your program will appear frozen the whole time, with 
the progressbar not updating. In fact, it will not likely appear 
onscreen at all. Yikes! 

To learn why that is, and how to address it, the next chapter takes 
a deeper dive into Tk's event loop. 


9. Event Loop 


At the end of the last chapter, we explained how to use a progressbar 
to provide feedback to users about long-running operations. The 
progressbar itself was simple: call it's start method, perform your 
operation, and then call it's stop method. Unfortunately, you learned 
that if you tried this, your application will most likely appear completely 
frozen. 

To understand why, we need to revisit our discussion of event 
handling, way back in the Tk Concepts chapter. As we've seen, after 
we construct an application's initial user interface, it enters the Tk 
event loop. In the event loop, it continually processes events, pulled 
from the system event queue, usually dozens of times a second. It 
watches for mouse or keyboard events, invoking command callbacks 
and event bindings as needed. 

Less obviously, all screen updates are processed only in the event 
loop. For example, you may change the text of a label widget. 
However, that change doesn't appear onscreen immediately. Instead, 
the widget notifies Tk that it needs to be redrawn. Later on, in between 
processing other events, Tk's event loop will ask the widget to redraw 
itself. A/l drawing occurs only in the event loop. The change appears to 
happen immediately because the time between making the change to 
the widget and the actual redraw in the event loop is so small. 


Event Queue 


if no events 
left in queue 


Event Loop 


¢ 


Event loop showing application callbacks and screen updates. 


9.1. Blocking the Event Loop 


Where you run into problems is when the event loop is prevented from 
processing events for a lengthy period of time. Your application won't 
redraw or respond to events and will appear to be frozen. The event 
loop is said to be blocked. How can this happen? 

Let's start by visualizing the event loop as an execution timeline. In a 
normal situation, each deviation from the event loop (callback, screen 
update) takes only a fraction of a second before returning control to the 
event loop. 


Event #1 Event #2 Event #3 Event #4 
callback callback callback callback 


screen update 
Execution timeline for well-behaved event loop. 


In our scenario, the whole thing probably got started from an event like 
a user pressing a button. So the event loop calls our application code 
to handle the event. Our code creates the progressbar, performs the 
(lengthy) operations, and stops the progressbar. Only then does our 
code return control back to the event loop. No events have been 
processed in the meantime. No screen redrawing has occurred. 
They've just been piling up in the event queue. 


button press event 


callback 


start rt finish 
progressbar operation operation progressbar 


Event #2 Event #99 
callback callback 


Event #3 
Event #4 
Event #5 
Event #6 
Event loop ——+' = \f~ 


screen update 
Lengthy callback blocking the event loop. 


To prevent blocking the event loop, it's essential that event handlers 
execute quickly and return control back to the event loop. 

If you do have a long-running operation to perform, or anything like 
network I/O that could potentially take a long time, there are a few 
different approaches you can take. 


AX. For the more technically-inclined, Tk uses a single-threaded, event-driven 
programming model. All the GUI code, the event loop, and your 
application run within the same thread. Because of this, any calls or 

computations that block event handlers are highly discouraged. Some other GUI 
toolkits use different models that allow for blocking code, runs the GUI and event 
handlers in separate threads from application code, etc. Attempting to shoehorn 
these models into Tk can be a recipe for frustration and lead to fragile and hacky 
code. If you respect Tk's model rather than try to fight with it, you won't run into 
problems. 


9.2. One Step at a Time 


If possible, the very best thing you can do is break your operation into 
very small steps, each of which can execute very quickly. You let the 
event loop be responsible for when the next step occurs. That way, the 
event loop continues to run, processing regular events, updating the 
screen, and, in between all that, calling your code to perform the next 
step of the operation. 

To do this, we make use of timer events. Our program can ask the 
event loop to generate one of these events at some time in the future. 
As part of its regular work, when the event loop reaches that time, it will 
call back into our code to handle the event. Our code would perform 
the next step of the operation. It then schedules another timer event for 
the next step of the operation and immediately returns control back to 
the event loop. 


Timer #1 Timer #2 Timer #3 Timer #n 
Step #1 Step #2 Step #2 Step #Last 
- schedule ~ schedule - schedule - no further timer 

timer #2 timer #3 timer #4 scheduled 


Event #1 
callback 


- schedule 


Event #2 
timer #1 callback 
ne oe \ comme > \ 


_JN | 
Event loop 
screen update 


Breaking up a large operation into small steps tied together with timer events. 


Tk's after Command can be used to generate timer events. You 
provide the number of milliseconds to wait until the event should be 
fired. It may happen later than that if Tk is busy processing other 
events but won't happen before that. You can also ask that an idle 
event be generated; it will fire when no other events in the queue need 
to be processed. (Tk's screen updates and redraws occur in the 
context of idle events.) You can find more details on after in the 
reference manual. 
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In the following example, we'll perform a long operation that is broken 
up into 20 small steps. While this operation is being performed, we'll 
update a progressbar, and also allow users to interrupt the operation. 


def start(): 
b.configure (text='Stop', command=stop) 
l['text'] = 'Working...' 


global interrupt; interrupt = False 
root.after(1, step) 


def stop(): 
global interrupt; interrupt 


True 


def step (count=0): 
p['value'] = count 
if interrupt: 
result (None) 
return 
root.after(100) # next step in our operation; don't take 
too long! 
if count == 20: # done! 
result (42) 
return 
root.after(1, lambda: step(count+1) ) 


def result (answer): 


p['value'] = 0 

b.configure (text='Start!', command=start) 

l['text'] = "Answer: " + str(answer) if answer else "No 
Answer" 
f = ttk.Frame(root); f.grid() 
b = ttk.Button(f, text="Start!", command=start); 
b.grid(column=1, row=0, padx=5, pady=5) 
1 = ttk.Label(f, text="No Answer"); 1.grid(column=0, row=0, 
padx=5, pady=5) 
p = ttk.Progressbar(f, orient="horizontal", mode="determinate", 


maximum=20); 
p-grid(column=0, row=1, padx=5, pady=5) 


https://tkdocs.com/code/longrunning.py 


AX To interrupt the process, we've just set a global variable, which is checked 
next time the timer event fires. Another option would be to cancel the 
pending timer event. When we create the timer event, it returns an id 


number to uniquely identify the pending timer. To cancel it, we can call the 
after cancel method, passing it that unique id. 


You'll also note that we used a blocking form of after to simulate performing our 
operation. Rather than scheduling an event to occur in future, the call blocks, 
waiting a given time before returning. It works the same aS a sicep System call. 


9.3. Asynchronous I/O 


Timer events take care of breaking up a long-running computation, 
where you know that each step can be guaranteed to complete quickly 
so that your handler will return to the event loop. What if you have an 
operation that may not complete quickly? This can happen when you 
make a variety of calls to the operating system. The most common is 
when we're doing some kind of I/O, whether writing a_ file, 
communicating with a database, or retrieving data from a remote web 
server. 

Most I/O calls are blocking. They don't return until the operation 
completes (or fails). What we want to use instead are non-blocking or 
asynchronous |/O calls. When you make an asynchronous I/O call, it 
returns immediately, before the operation is completed. Your code can 
continue running, or in this case, return back to the event loop. Later 
on, when the I/O operation completes, your program is notified and can 
process the result of the I/O operation. 

If this sounds like treating I/O as another type of event, you're 
exactly right. In fact, it's also called event-driven I/O. 

In Python, asynchronous 1|/O is provided through the asyncio 
module, as well as many other modules that are layered on top of it. 

All asyncio applications rely heavily on an event loop. How 
convenient, Tkinter has a great event loop! Unfortunately, the asyncio 
event loop and the Tkinter event loop are not the same. You can't really 
have both of them running at the same time, at least within the same 
thread (well, you can have one call repeatedly into the other, but it's 
pretty hacky and fragile). 

My recommendation: keep Tkinter in the main thread, and spin off 
your asyncio event loops in another thread. 

Your application code, running in the main thread, may need to 
coordinate with the asyncio event loop running in the other thread. You 
can call a function running in the asyncio event loop thread (even from 
the Tkinter event loop, e.g., in a widget callback) using the asyncio 
call_soon threadsafe method. To call Tkinter from the asyncio event 
loop, keep reading. 


9.4. Threads or Processes 


Sometimes it's either not possible or practical to break up a long- 
running computation into discrete pieces that each run quickly. Or you 
may be using a library that doesn't support asynchronous operations. 
Or, like Python's asyncio, it doesn't play nice with Tk's event loop. In 
cases like these, to keep your Tk GUI responsive, you'll need to move 
those time-consuming operations or library calls out of your event 
handlers and run them somewhere else. Threads, or even other 
processes, can help with that. 

Running tasks in threads, communicating with them, etc. is beyond 
the scope of this book. However, there are some restrictions on using 
Tk with threads that you should be aware of. The main rule is that you 
must only make Tk calls from the thread where you loaded Tk. 

Tkinter goes to great lengths internally so you make Tkinter calls 
from multiple threads. It routes them to the main thread (the one that 
created the Tk instance). It mostly works, but not always. Despite all it 
tries to do, | highly recommend you make all Tkinter calls from a single 
thread. 

If you need to communicate from another thread to the thread 
running Tkinter, Keep it as simple as possible. Use event generate to 
post a virtual event to the Tkinter event queue, and then bina to that 
event in your code. 

It can be even more complicated. The Tcl/Tk libraries can be built 
either with or without thread support. If you have more than one thread 
in your application, make sure you're running in a threaded build. If 
you're unsure, check the Tcl variable tcl _platform(threadea) }; It should 
be i, not o. 


>>> tkinter.Tcl() .eval(' set tcl_platform(threaded)' ) 


fYZ Most everyone should be running threaded builds. The ability to create 

non-threaded builds in Tcl/Tk is likely to go away in future. If you're using 

a non-threaded build with threaded code, consider this a bug in your 
application, not a challenge to make it work. 


9.5. Nested Event Processing 


The previous three approaches are the correct ways to handle long- 
running operations while still keeping you Tk GUI responsive. What 
they have in common is a single event loop that continuously 
processes events of all kinds. That event loop will call event handlers 
in your application code, which do their thing and quickly return. 

There is one other way. Within your long-running operation, you can 
invoke the event loop to process a bunch of events. You can do this 
with a single command, update. There's no messing around with timer 
events or asynchronous I/O. Instead, you just sprinkle some update 
calls throughout your operation. If you want to only keep the screen 
redrawing but not process other events, there's even an option for that 
(update _idletasks). 

This approach is seductively easy. And if you're lucky, it might work. 
At least for a little while. But sooner or later, you're going to run into 
serious difficulties trying to do things that way. Something won't be 
updating, event handlers aren't getting called that should be, events 
are going missing or being fired out of order, or worse. You'll turn your 
program's logic inside out and tear your hair out trying to make it work 
again. 


AX. When you UuS@€ update, you're not returning control back to the running 
event loop. You're effectively starting a new event loop nested within the 
existing one. Remember, the event loop follows a single thread of 

execution: no threads, no coroutines. If you're not careful, you're going to end up 
with event loops called from within event loops called from... well, you get the 
idea. If you even realize you're doing this, unwinding the event loops (each of 
which may have different conditions to terminate it) will be an interesting exercise. 
The reality won't match with your mental model of a simple event loop dispatching 
events one at a time, independent of every other event. It's a classic example of 
fighting against Tk's model. In very specific circumstances, it's possible to make it 
work. In practice, you're asking for trouble. Don't say you haven't been warned... 


Nested event loops... this way madness lies. 


10. Menus 


This chapter describes how to handle menubars and popup menus in 
Tk. For a polished application, these are areas you particularly want 
to pay attention to. Menus need special care if you want your 
application to fit in with other applications on your users’ platform. 

Speaking of which, the recommended way to figure out which 
platform you're running on is: 


root.tk.call('tk', 'windowingsystem') # returns xl1, win32 
Or aqua 


Tkinter does not provide a direct equivalent to this call. However, it is 

possible to directly execute an arbitrary Tcl-based Tk command, using 

the tk.call() method available on any Tkinter widget. Here, we're 
invoking the Tcl/Tk command tk windowingsystem. 


This is more useful than examining global variables like ¢ci_platform or 
sys.platform, and older checks that used these methods should be 
reviewed. While in the olden days, there was a pretty good correlation 
between platform and windowing system, it's less true today. For example, if 
your platform is identified on Unix, that might mean Linux under X11, macOS 
under Aqua, or even macOS under X11. 


UPGRADE 
Pesascab sisted 


10.1. Menubars 


In this section, we'll look at menubars: how to create them, what goes 
in them, how they're used, etc. 

Properly designing a menubar and its set of menus is beyond the 
scope of this book. However, if you're creating an application for 
someone other than yourself, here is a bit of advice. First, if you find 
yourself with many menus, very long menus, or deeply nested 
menus, you may need to rethink how your user interface is organized. 
Second, many people use the menus to explore what the program 
can do, particularly when they're first learning it, so try to ensure 
major features are accessible by the menus. Finally, for each platform 
you're targeting, become familiar with how applications use menus, 
and consult the platform's human interface guidelines for full details 
about design, terminology, shortcuts, and much more. This is an area 
you will likely have to customize for each platform. 
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Menubars. 


XL. You'll notice on some recent Linux distributions that many applications 
show their menus at the top of the screen when active, rather than in 
the window itself. Tk does not yet support this style of menus. 


Menu Widgets and Hierarchy 


Mm Menu 
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Menus are implemented as widgets in Tk, just like buttons and 
entries. Each menu widget consists of a number of different items in 
the menu. Items have various attributes, such as the text to display 
for the item, a keyboard accelerator, and a command to invoke. 

Menus are arranged in a hierarchy. The menubar is itself a menu 
widget. It has several items ("File," "Edit," etc.), each of which is a 
submenu containing more items. These items can include things like 
the "Open..." command in a "File" menu, but also separators between 
other items. It can even have items that open up their own submenu 
(so-called cascading menus). As you'd expect from other things 
you've seen already in Tk, anytime you have a submenu, it must be 
created as a child of its parent menu. 

Menus are part of the classic Tk widgets; there is not presently a 
menu in the themed Tk widget set. 


Before you Start 


It's essential to put the following line in your application somewhere 
before you start creating menus. 


root.option add("*tearOrti*, FALSE) 


Without it, each of your menus (on Windows and X11) will start with 
what looks like a dashed line and allows you to "tear off" the menu, so 
it appears in its own window. You should eliminate tear-off menus 
from your application as they're not a part of any modern user 
interface style. 


This is a throw-back to the Motif-style X11 that Tk's original look and 
feel were based on. Get rid of them unless your application is designed 
to run only on that old box collecting dust in the basement. We'll all look 
forward to a future version of Tk where this misguided paean to backward 
compatibility is removed. 


UPGRADE 
Peston 


While on the topic of ancient history, the option ada bit uses the option 
database. On X11 systems, this provided a standardized way to customize 


certain elements of user interfaces through text-based configuration files. It's no 
longer used today. Older Tk programs may use the option command internally 
to separate style configuration options from widget creation code. This all pre- 
dated themed Tk styles, which should be used for that purpose today. However, 
it's somehow fitting to use the obsolete option database to automatically remove 
the obsolete tear-off menus. 


Creating a Menubar 


In Tk, menubars are associated with individual windows; each 
toplevel window can have at most one menubar. On Windows and 
many X11 window managers, this is visually obvious, as the menus 
are part of each window, sitting just below the title bar at the top. 

On macOS, though, there is a single menubar along the top of the 
screen, shared by each window. As far as your Tk program is 
concerned, each window still does have its own menubar. As you 
switch between windows, Tk ensures that the correct menubar is 
displayed. If you don't specify a menubar for a particular window, Tk 
will use the menubar associated with the root window; you'll have 
noticed by now that this is automatically created for you when your Tk 
application starts. 


Because all windows have a menubar on macOS, it's important to 

define one, either for each window or a fallback menubar for the root 

window. Otherwise, you'll end up with the "built-in" menubar, which 
contains menus that are only intended for typing commands directly into the 
interpreter. 


To create a menubar for a window, first, create a menu widget. Then, 
use the window's menu configuration option to attach the menu widget 
to the window. 


win = Toplevel (root) 
menubar = Menu (win) 
win['menu'] = menubar 


You can use the same menubar for more than one window. In other 
words, you can specify the same menubar as the menu configuration 
option for several toplevel windows. This is particularly useful on 


Windows and X11, where you may want a window to include a menu, but don't 
necessarily need to juggle different menus in your application. However, if the 
contents or state of menu items depends on what's going on in the active 
window, you'll have to manage this yourself. 


This is truly ancient history, but menubars used to be implemented by 
creating a frame widget containing the menu items and packing it into 
the top of the window like any other widget. Hopefully, you don't have 
any code or documentation that still does this. 


UPGRADE 


Adding Menus 


We now have a menubar, but that's pretty useless without some 
menus to go in it. So again, we'll create a menu widget for each 
menu, each one a child of the menubar. We'll then add them all to the 
menubar. 


menubar = Menu (parent) 

menu_file = Menu (menubar) 

menu_edit = Menu (menubar) 

menubar,add cascade (menu=menu file, label="File") 
menubar.add cascade (menu=menu ¢dit, label="Edit") 


XL. The add cascade method adds a menu item, which itself is a menu (a 
submenu). 


Adding Menu Items 


Now that we have a couple of menus in our menubar, we can add a 
few items to each menu. 


Command Items 


Regular menu items are called command items in Tk. We'll see some 
other types of menu items shortly. Notice that menu items are part of 
the menu itself; we don't have to create a separate menu widget for 
each one (submenus being the exception). 


menu_file = Menu (menubarmenu_file.add_command(label='New', 
command=newFile) 

menu_file.add_command(label='Open...', command=openFile) 
menu_file.add_command(label='Close', command=closeFile) 


XL. On macOS, the ellipsis ("...") is actually a special character, more tightly 
spaced than three periods in a row. Tk takes care of substituting this 
character for you automatically. 


Each menu item has associated with it several configuration options, 
analogous to widget configuration options. Each type of menu item 
has a different set of available options. Cascade menu items have a 
menu Option used to specify the submenu, command menu items have 
a command option to specify the command to invoke when the item is 
chosen. Both have a iabe1 option to specify the text to display for the 
item. 


Submenus 


We've already seen cascade menu items used to add a menu to a 
menubar. Not surprisingly, if you want to add a submenu to an 
existing menu, you alSo use a cascade Menu item in exactly the same 
way. You might use this to build build a "recent files" submenu, for 
example. 


menu_recent = Menu(menu_file) 

menu file.add cascade (ménu=menu, recent, labéel="Opéen Recent”) 

for fin recent. Tiles: 
menu_recent.add_ command (label=os.path.basename(f), 

command=lambda: openFile(f)) 


https: //tkdocs.com/code/recenttiles. py 
Separators 


A third type of menu item is the separator, which produces the 
dividing line you often see between different menu items. 


menu_file.add_ separator () 


Checkbutton and Radiobutton Items 


Finally, there are also checkbutton and radiobutton menu items that 
behave analogously to checkbutton and radiobutton widgets. These 
menu items have a variable associated with them. Depending on its 
value, an indicator (i.e., checkmark or selected radiobutton) may be 
shown next to its label. 


check = StringVar() 

menu Tilé.edd checkbutton (lLabel="Check’, variable=chsck, 
onvalue=l1, offvalue=0) 

radio = StringVar() 
menu_file.add_radiobutton(label='One', variable=radio, 
value=1) 
menu_file.add_radiobutton(label='Two', variable=radio, 
value=2) 


When a user selects a checkbutton item that is not already checked, 
it sets the associated variable to the value in onvalue. Selecting an 
item that is already checked sets it to the value in offvalue. Selecting 
a radiobutton item sets the associated variable to the value in value. 
Both types of items also react to any changes you make to the 
associated variable. 

Like command items, checkbutton and radiobutton menu items 
support a command configuration option that is invoked when the menu 
item is chosen. The associated variable and the menu item's state 
are updated before the callback is invoked. 


Radiobutton menu items are not part of the Windows or macOS human 

interface guidelines. On those platforms, the item's indicator is a 

checkmark, as it would be for a checkbutton item. The semantics still 
work. It's a good way to select between multiple items since it will show one of 
them selected (checked). 


Manipulating Menu Items 


As well as adding items to the end of menus, you can also insert 
them in the middle of menus via the insert index type ?option 


value...? method; here index is the position (0..n-1) of the item you 
want to insert before. You can also delete one or more menu items 
susing the delete index ?endidx? method. 


menu. recent.delete (0, *end”™) 


Like most everything in Tk, you can look at or change the value of an 
item's options at any time. Items are referred to via an index. Usually, 
this is a number (0..n-1) indicating the item's position in the menu. 
You can also specify the label of the menu item (or, in fact, a "glob- 
style" pattern to match against the item's label). 


print ( menu file.entryeget (0, "label")) # get label of top 
entry in menu 

print ( menu Tilé.entryconfigure(Q) } # show all options for 
an item 
State 


You can disable a menu item so that users cannot select it. This can 
be done via the state option, setting it to the value disabied. Use a 
value of normal to re-enable the item. 

Menus should always reflect the current state of your application. If 
a menu item is not presently relevant (e.g., the "Copy" item is only 
applicable if something in your application is selected), you should 
disable it. When your application state changes so that the item is 
applicable, make sure to enable it. 


menu filé.entryconfigure (’"Closé*, state=DISABLED) 


Sometimes you may have menu items whose name changes in 
response to application state changes, rather than the menu item 
being disabled. For example, A web browser might have a menu item 
that changes between "Show Bookmarks" and "Hide Bookmarks" as 
a bookmarks pane is hidden or displayed. 


menu_bookmarks.entryconfigure(3, label="Hide Bookmarks") 


As your program grows complex, it's easy to miss enabling or disabling 

some items. One strategy is to centralize all the menu state changes in 

one routine. Whenever there is a state change in your application, it 
should call this routine. It will examine the current state and update menus 
accordingly. The same code can also handle toolbars, status bars, or other user 
interface components. 


Accelerator Keys 


The accelerator option is used to indicate a keyboard equivalent that 
corresponds to a menu item. This does not actually create the 
accelerator, but only displays it next to the menu item. You still need 
to create an event binding for the accelerator yourself. 


Remember that event bindings can be set on individual widgets, all 

widgets of a certain type, the toplevel window containing the widget 

you're interested in, or the application as a whole. As menu bars are 
associated with individual windows, the event bindings you create will usually 
be on the toplevel window the menu Is associated with. 


Accelerators are very platform-specific, not only in terms of which 
keys are used for what operation, but what modifier keys are used for 
menu accelerators (e.g., on macOS, it is the "Command" key, on 
Windows and X11, it is usually the "Control" key). Examples of valid 
accelerator options are command-N, Shift+Ctr1+x, and Command-Option- 
B. Commonly used modifiers include control, Ctrl, Option, Opt, Alt, 
Shift, "Command, Cmd, and Meta. 


fYZ On macOS, modifier names are automatically mapped to the different 
modifier icons that appear in menus, i.€., shift > ff, Command > &, 
Control > “ and option > ~% 


menu_bookmarks.entryconfigure(3, label="Hide Bookmarks") 


Underline 


All platforms support keyboard traversal of the menubar via the arrow 
keys. On Windows and X11, you can also use other keys to jump to 
particular menus or menu items. The keys that trigger these jumps 
are indicated by an underlined letter in the menu item's label. To add 
one of these to a menu item, use the underline configuration option 
for the item. Its value should be the index of the character you'd like 
underlined (from O to the length of the string - 1). Unlike with 
accelerator keys, the menu will watch for the keystroke, so no 
separate event binding is needed. 


m.add command (label="Path Browser’, underline=5) # underline 
es 


Images 


It is also possible to use images in menu items, either beside the 
menu item's label, or replacing it altogether. To do this, use the image 
and compound options, which work just like in label widgets. The value 
for image must be a Tk image object, while compound can have the 
values bottom, center, left, right, top, Of none. 


Menu Virtual Events 


Platform conventions for menus suggest standard menus and items 
that should be available in most applications. For example, most 
applications have an "Edit" menu, with menu items for "Copy," 
"Paste," etc. Tk widgets like entry or text will react appropriately when 
those menu items are chosen. But if you're building your own menus, 
how do you make that work? What command would you assign to a 
"Copy" menu item? 

Tk handles this with virtual events. As you'll recall from the Tk 
Concepts chapter, these are high-level application events, as 
opposed to low-level operating system events. Tk's widgets will watch 
for specific events. When you build your menus, you can generate 
those events rather than directly invoking a callback function. Your 
application can create event bindings to watch for those events too. 


Some developers create virtual events for every item in their menus. They 
generate those events instead of calling routines in their own code 
directly. It's one way of splitting off your user interface code from the 
rest of your application. Remember that even if you do this, you'll still 

need code that enables and disables menu items, adjusts their labels, etc. in 

response to application state changes. 


Here's a minimal example showing how we'd add two items to an 
"Edit" menu, the standard "Paste" item, and an application-specific 
"Find..." item that will open a dialog to find or search for something. 
We'll include an entry widget so that we can check that "Paste" 
works. 


from tkinter import * 
from tkinter import ttk, messagebox 


root = Tk() 

ttk. Entry (root) .grid() 

m = Menu(root) 

m_ edit = Menu (m) 

M.add Ccascads (ménu=m: edit, Jabsl="Edit™) 
m_edit.add_command(label="Paste", command=lambda: 
fOOE.FOCUS get l).event generate ("<<Paste>>")) 


m_edit.add_command(label="Find...", command=lambda: 
root.event_ generate ("<<OpenFindDialog>>") ) 
root ["*menu')] = m 


def launchFindDialog(*args): 
messagebox.showinfo(message="I hope you find what you're 
looking for!") 


root.bind("<<OpenFindDialog>>", launchFindDialog) 
root.mainloop () 


https://tkdocs.com/code/menu.py. 


When you generate a virtual event, you need to specify the widget that 
the event should be sent to. We want the "Paste" event to be sent to the 
widget with the keyboard focus (usually indicated by a focus ring). You 
can determine which widget has the keyboard focus using the focus command. 
Try it out, choosing the Paste item when the window is first opened (when 
there's no focus) and after clicking on the entry (making it the focus). Notice the 


entry handles the <<paste>> event itself. There's no need for us to create an 
event binding. 


The <<openFindDialog>> event is sent to the root window, which is where we 
create an event binding. If we had multiple toplevel windows, we'd send it to a 
specific window. 


Tk predefines the following virtual events: <<clear>>, <<Copy>>, 
<<Cut>>, <<Paste>>, <<PasteSelection>>, <<PrevWindow>>, <<Redo>>, 
and <<undo>>. For additional information, see the event command 
reference. 
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10.2. Platform Menus 


Each platform has a few menus in every menubar that are handled 
specially by Tk. 


macOS 


You've probably noticed that Tk on macOS supplies its own default 
menubar. It includes a menu named after the program being run (in 
this case, your programming language's shell, "Python"), a File menu, 
and standard Edit, Windows, and Help menus, all stocked with 
various menu items. 

You can override this menubar in your own program, but to get the 
results you want, you'll need to follow some particular steps (in some 
cases, in a particular order). 


a Starting at Tk 8.5.13, the handling of special menus on macOS changed 


UPGRADE 


waa Que to the underlying Tk code migrating from the obsolete Carbon API 
to Cocoa. If you're seeing duplicate menu names, missing items, things 
you didn't put there, etc. review this section carefully. 


The first thing to know is that if you don't specify a menubar for a 
window (or its parent window, e.g., the root window), you'll end up 
with the default menubar Tk supplies, which unless you're just 
mucking around on your own, is almost certainly not what you want. 


The Application Menu 


Every menubar starts with the system-wide apple icon menu. To the 
right of that is a menu for the frontmost application. It is always 
named after the binary being run. If you do supply a menubar, at the 
time the menubar is attached to the window, if there is not a specially 
named .apple menu (see below), Tk will provide its default 
application menu. It will contain an "About Tcl & Tk" item, followed by 
the standard menu items: preferences, the services submenu, 
hide/show items, and quit. Again, you don't want this. 


If you supply your own .apple menu, when the menubar is 
attached to the window, Tk will add the standard items (preferences 
and onward) onto the end of any items you have added. Perfect! 
Items you add after the menubar is attached to the window will 
appear after the quit item, which, again, you don't want. 


@ The application menu, which we're dealing with here, is distinct from the 


apple menu (the one with the apple icon, just to the left of the 
application menu). Despite that, we really mean the application menu, 


even though Tk still refer to it as the "apple" menu. This is a holdover from pre- 
OS X days when these sorts of items did go in the actual apple menu, and there 
was no separate application menu. 


So, 


1. 


Wi 
me 


in other words, in your program, make sure you: 


Create a menubar for each window or the root window. Do not 
attach the menubar to the window yet! 


. Add a menu to the menubar named .appie. It will be used as the 
application menu. 


. The menu will automatically be named the same as the 
application binary; if you want to change this, rename (or make a 
copy of) the binary used to run your script. 


Add the items you want to appear at the top of the application 
menu, i.e., an "About yourapp" item, followed by a separator. 


. After you have done all this, you can then attach the menubar to 
your window via the window's menu configuration option. 


n = Toplevel (root) 
nubar = Menu (win) 


appmenu = Menu(menubar, name='apple') 


me 


nubar.add_cascade (menu=appmenu) 


appmenu.add_command(label='About My Application') 
appmenu.add_ separator () 


wi 


n['menu'] = menubar 


XL. While usually, Tkinter chooses a widget pathname for us, we've had to 


explicitly provide one (apple) using the name option when creating the 
application menu. 


Handling the Preferences Menu Item 


As you've noticed, the application menu always includes a 
"Preferences..." menu item. If your application has a preferences 
dialog, this menu item should open it. If your application has no 
preferences dialog, this menu item should be disabled, which it is by 
default. 

To hook up your preferences dialog, you'll need to define a Tcl 
procedure named ::tk::mac::ShowPreferences. This will be called 
when the Preferences menu item is chosen; if the procedure is not 
defined, the menu item will be disabled. 


def showMyPreferencesDialog(): 


root.createcommand('tk::mac::ShowPreferences', 
showMyPreferencesDialog) 


Providing a Help Menu 


Like the application menu, any help menu you add to your own 
menubar is treated specially on macOS. As with the application menu 
that needed a special name (.appie), the help menu must be given 
the name .nhelp. Also, like the application menu, the help menu 
should also be added before the menubar is attached to the window. 

The help menu will include the standard macOS search box to 
search help, as well as an item named "yourapp Help." As with the 
name of the application menu, this comes from your program's 
executable and cannot be changed. Similar to how preferences 
dialogs are handled, to respond to this help item, you need to define 
a Tcl procedure named : :tk::mac::ShowHelp. If this procedure is not 
defined, it will not disable the menu item. Instead, it will generate an 
error when the help item is chosen. 


Q If you don't want to include help, don't add a help menu to the menubar, 
and none will be shown. 


ye on X11 and earlier versions of Tk on macOS, the Help menu will not 
automatically be put at the end of the menubar, so ensure it is the last 

‘amma = menu added. 

You can also add other items to the help menu. These will appear 

after the application help item. 


helpmenu = Menu(menubar, name='help') 
menubar.add cascade (menu=helpmenu;, label="Help') 
root.createcommand('tk::mac::ShowHelp', ...) 


Providing a Window Menu 


On macOS, a "Window" menu contains items like minimize, zoom, 
bring all to front, etc. It also includes a list of currently open windows. 
Before that list, other application-specific items are sometimes 
provided. 

By providing a menu named .window, this standard window menu 
will be added. Tk automatically keeps it in sync with all your toplevel 
windows, without any extra code on your part. You can also add any 
application-specific commands to this menu. These appear before the 
list of your windows. 


windowmenu = Menu(menubar, name='window') 
menubar.add_cascade (menu=windowmenu, label='Window') 


Other Menu Handlers 


You saw previously how handling certain standard menu items 
required you to define Tcl callback procedures,’ e.g., 
tk::mac::ShowPreferences and tk::mac::ShowHelp. 

There are several other callbacks that you can define. For 
example, you might intercept the Quit menu item, prompting users to 
save their changes before quitting. Here is the complete list: 


tk: :mac::ShowPreferences: 
Called when the "Preferences..." menu item is selected. 


ER: 


tk: 


tke 


tees 


:mac::ShowHelp: 


Called to display main online help for the application. 


smac?: OU : 


Called when the Quit menu item is selected, when a user is 
trying to shut down the system etc. 


::mac::OnHide: 


Called when your application has been hidden. 


:imac::OnShow: 


Called when your application is shown after being hidden. 


:imac::OpenApplication: 


Called when your application is first opened. 


:i:mac::ReopenApplication: 


Called when a user "reopens" your already-running application 
(e.g. clicks on it in the Dock) 


:mac::OpenDocument: 


Called when the Finder wants the application to open one or 
more documents (e.g. that were dropped on it). The procedure is 
passed a list of pathnames of files to be opened. 


:mac::PrintDocument: 


As with OpenDocument, but the documents should be printed 
rather than opened. 


For additional information, see the tk_mac command reference. 


[3 https://tkdocs.com/man/tk_mac 


Windows 


On Windows, each window has a "System" menu at the top left of the 
window frame, with a small icon for your application. It contains items 
like "Close", "Minimize", etc. In Tk, if you create a system menu, you 
can add new items that will appear below the standard items. 


sysmenu = Menu(menubar, name='system') 
menubar.add_cascade (menu=sysmenu) 


AYE. While usually, Tkinter will choose a widget pathname for us, we've had 


to explicitly provide one with the name system; this is the cue that Tk 
needs to recognize it as the system menu. 


X11 


On X11, if you create a help menu, Tk will ensure that it is always the 
last menu in the menubar. 


menu help. = Menu(menubar, name="help* } 
menubar.add cascade (menu=menu help, label='Help") 


AXE. While usually, Tkinter will choose a widget pathname for us, we've had 
to explicitly provide one with the name help; this is the cue that Tk 
needs to recognize it as the help menu. 


10.3. Contextual Menus 


Contextual menus ("popup" menus) are typically invoked by a right 
mouse button click on an object in the application. A menu pops up at 
the location of the mouse cursor. Users can then select an items from 
the menu (or click outside it to dismiss it without choosing any item). 

To create a contextual menu, we'll use exactly the same 
commands we did to create menus in the menubar. Typically, we'd 
create one menu with several command items in it, and potentially 
some cascade menu items and their associated menus. 

To activate the menu, users will perform a contextual menu click. 
We'll have to create an event binding to capture that click. That, 
however, can mean different things on different platforms. On 
Windows and X11, this is the right mouse button being clicked (the 
third mouse button). On macOS, this is either a click of the left (or 
only) button with the control key held down or a right-click on a multi- 
button mouse. Unlike Windows and X11, macOS refers to this as the 
second mouse button, not the third, so that's the event we'll see in 
our program. 


1. Most earlier programs that have used popup menus assumed it was 
‘mamx only "button 3" they needed to worry about. 
Besides capturing the correct contextual menu event, we also need to 
capture the mouse's location. It turns out we need to do this relative 
to the entire screen (global coordinates) and not local to the window 
or widget you clicked on (local coordinates). The sx and sy 
substitutions in Tk's event binding system will capture those for us. 
The last step is simply to tell the menu to pop up at the particular 
location, via the post method. Here's an example of the whole 
process, using a popup menu on the application's main window. 


from tkinter import * 

root = Tk() 

menu = Menu(root) 

for iin ('One', 'Two', 'Three'): 


menu.add_command (label=1i) 
if (root.tk.call('tk', 'windowingsystem')=='aqua'): 
roov,.bind('<2>", lambda ¢; menu.post(¢.% root, Gsy root) ) 
root.bind('<Control-1>', lambda e€: menu.post(é.x root, 
ea TOot)) 
else: 
POOL, Di ng{*<5>",. lambda oF Menu. post (Sek. Fool, Gey roor)) 
root.mainloop () 


https://tkdocs.com/code/contextmenu. py 


11. Windows and Dialogs 


Everything we've done up until now has been in a single window. In 
this chapter, we'll cover how to use multiple windows, changing 
various attributes of windows, and use some of the standard dialog 


boxes that are available in Tk. 


11.1. Creating and Destroying Windows 


We've seen that all Tk programs start out with a root toplevel window, 
and then widgets are created as children of that root window. 
Creating new toplevel windows works almost exactly the same as 
creating new widgets. 

Toplevel windows are created using the Toplevel class: 


t = Toplevel (parent) 


Note: Toplevels are part of the classic Tk widgets, not the themed 
widgets. 

Unlike regular widgets, we don't have to grid a toplevel for it to 
appear onscreen. Once we've created a new toplevel, we can create 
other widgets as children of that toplevel, and gria them inside the 
toplevel. The new toplevel behaves exactly like the automatically 
created root window. 

To destroy a window, use its destroy method: 


window.destroy() 


Note that you can use destroy On any widget, not just a toplevel 
window. When you destroy a window, all windows (widgets) that are 
children of that window are also destroyed. Be careful! If you destroy 
the root window (that all other widgets are descended from), that will 
terminate your application. 


q\ In a typical document-oriented application, we want to be able to close 
any windows while leaving the others open. In that case, we may want 
to create a new toplevel for every window, and not put anything directly 

inside the root window at all. While we can't just destroy the root window, we 

can remove it entirely from the screen using its withdraw method, which we'll 
see shortly. 


11.2. Window Behavior and Styles 


There are lots of things about how windows behave and how they 
look that can be changed. 


Window Title 


To examine or change the title of the window: 


oldtitle = window.title() 
window.title('New title') 


Size and Location 


In Tk, a window's position and size on the screen are known as its 
geometry. A full geometry’ specification looks like _ this: 
widthxheight x y.t t 

Width and height (usually in pixels) are pretty self-explanatory. The 
x (horizontal position) is specified with a leading plus or minus, so +25 
means the left edge of the window should be 25 pixels from the left 
edge of the screen, while -50 means the right edge of the window 
should be 50 pixels from the right edge of the screen. Similarly, a y 
(vertical) position of +10 means the top edge of the window should be 
ten pixels below the top of the screen, while -100 means the bottom 
edge of the window should be 100 pixels above the bottom of the 
screen. 


Geometry specifies the actual coordinates on the screen. It doesn't 

make allowances for systems like macOS with a menubar along the top 

or a dock along the bottom. So specifying a position of +0+0 would 
actually place the top part of the window under the system menu bar. It's a good 
idea to leave a healthy margin (at least 30 pixels) from the screen's edge. 


Screen positions can be different than you might expect when you have multiple 
monitors on your system. We'll cover that shortly. 


Here is an example of changing the size and position. It places the 
window towards the top righthand corner of the screen: 


window.geometry ('300x200-5+40"') 


You can retrieve the current geometry the same way; just don't 
provide a new geometry value. However, if you try it immediately after 
changing the geometry, you'll find it doesn't match. Remember that all 
drawing effectively occurs in the background, in response to idle 
times via the event loop. Until that drawing occurs, the internal 
geometry of the window won't be updated. If you do want to force 
things to update immediately, you can. 


window.update idletasks () 
print (window.geometry ()) 


We've seen that the window defaults to the size requested by the 

widgets that are gridded into it. If we're creating and adding new widgets 

interactively in the interpreter, or if our program adds new widgets in 
response to other events, the window size adjusts. This behavior continues until 
either we explicitly provide the window's geometry as above or a user resizes 
the window. At that point, even if we add more widgets, the window won't 
change size. You'll want to be sure you're using all of gria's features (e.g., 
sticky, weight) to make everything fit nicely. 


Resizing Behavior 


By default, toplevel windows, including the root window, can be 
resized by users. However, sometimes you may want to prevent 
users from resizing the window. You can do this via the resizable 
method. It's first parameter controls whether users can change the 
width, and the second if they can change the height. So to disable all 
resizing: 


window.resizable (FALSE, FALSE) 


If a window is resizable, you can specify a minimum and/or maximum 
size that you'd like the window's size constrained to (again, 
parameters are width and height): 


window.minsize(200,100) 
window.maxsize (500,500) 


You saw earlier how to obtain the current size of the window via its 
geometry. Wondering how large it would be if you didn't specify its 
geometry, or a user didn't resize it? You can retrieve the window's 
requested size, i.e., how much space it requests from the geometry 
manager. Like with drawing, geometry calculations are only done at 
idle time in the event loop, so you won't get a useful response until 
the widget has appeared onscreen. 


window.winfo_ reqwidth () # or winfo_ reqheight 


AL. You can use the reqwidth and reqheight methods on any widget, not 
just toplevel windows. There are other winfo methods you can call on 
any widget, such as width and height, to get the actual (not requested) 

wig and height. For more, see the winfo command reference. 
= https: /Akdocs.com/man/Minfo 


intercepting the Close Button 


Most windows have a close button in their title bar. By default, Tk will 
destroy the window if users click on that button. You can, however, 
provide a callback that will be run instead. A common use is to 
prompt the user to save an open file if modifications have been made. 


window.protocol ("WM DELETE WINDOW", callback) 


AXE. The somewhat obscurely-named wm Dz 
X11 window manager protocols. 


E PRoTOCOL Originated with 


4 
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Transparency 


Windows can be made partially transparent by specifying an alpha 
channel, ranging from 0.0 (fully transparent) to 1.0 (fully opqaque). 


window.attributes("-alpha", 0.5) 


@ Tkinter's wrapper to the underlying wm attributes command doesn't do 
any interpretation of options, handle keyword arguments, etc. 


On macOS, you can additionally specify a -transparent attribute 
(using the same mechanism as with -aipha), which allows you to 
make the background of the window transparent, and remove the 
window's show. You should also set the background configuration 
option for the window and any frames to the color ssytemTransparent. 


Full Screen 


You can make a window expand to take up the full screen: 


window.attributes("-fullscreen", 1) 


Other macOS-Specific Attributes 


In addition to the -transparent attribute described above, macOS 
windows boast some additional attributes. 

The (red) close widget in the title bar can indicate that the content 
inside the window has been modified (e.g., the file needs to be 
saved). Set the -modifiea attribute to 1 to indicate this, or o to remove 
the modified indicator. 

You can draw users' attention to the window by bouncing its icon in 
the macOS dock. To do so, set the window's -notify attribute. 

If a window contains the contents of a document, you can place an 
icon in the title bar specifying the file the document refers to. Users 
can drag this icon as a proxy for dragging the file in the Finder. Set 
the window's -titlepath attribute to the full path of the file. Note that 


this does not change the title of the window (you'll need to change 
that separately), but just provides the icon. 

On macOS, windows can also take a variety of appearances for 
different purposes, e.g. utility windows, modal dialogs, floating 
windows, and so on. There is an unsupported command in Tk called 
MacWindowStyle that lets you assign one of these appearances to a 
window. Unlike many options in Tk which can be changed at any 
point, these appearances must be assigned after the window is 
created but before it appears onscreen. 


t = Toplevel (root) 
t.tk.call("::tk: :unsupported: :MacWindowStyle", "style", t. w, 
“HET lity") 


Besides utility, other useful appearance styles include floating, 
plain, and modal. 


XL. While officially unsupported, this feature has been available for a long 
time in Tk. It's likely in future to migrate to the wm attributes command. 
For further information, including more details on the different 
appearances and optional attributes, see the MacWindowStyle wiki page 
(https: /Wwiki.tcl-lang. org/page/MacWindowStyle). 


Iconifying and Withdrawing 


On most systems, you can temporarily remove the window from the 
screen by iconifying it. In Tk, whether or not a window is iconified is 
referred to as the window's state. The possible states for a window 
include normal and iconic (for an iconified window), and several 
others: withdrawn, icon OF zoomed. 

You can query or set the current window state directly. There are 
also methods iconify, deiconify, and withdraw, which are shortcuts 
for setting the iconic, normal, and withdrawn States, respectively. 


thestate = window.state() 
window.state('normal') 
window.iconify() 
window.deiconify() 
window.withdraw() 


Qa For document-centric applications, where you want to allow closing any 
window without the application exiting (as would happen if you destroy 
the root window), USeé withdraw on the root window to remove it from the 

screen, use new toplevel windows for your user interface. 


Stacking Order 


Stacking order refers to the order that windows are "placed" on the 
screen, from bottom to top. When the positions of two windows 
overlap each other, the one closer to the top of the stacking order will 
obscure or overlap the one lower in the stacking order. 

You can ensure that a window is always at the top of the stacking 
order (or at least above all others where this attribute isn't set): 


window.attributes("-topmost", 1) 


You can find the current stacking order, listed from lowest to highest: 


root.tk.eval('wm stackorder '+str(window) ) 


@ This method isn't exposed cleanly in Tkinter. It returns the internal 
names of each window, not the window object. 


You can also just check if one window is above or below another: 


if (root.tk.eval('wm stackorder '+str(window)+' isabove 
"+str(otherwindow))=='1"') ... 

if (root.tk.eval('wm stackorder '+str(window)+' isbelow 
"+str (otherwindow) )=='1") 


You can also raise or lower windows, either to the very top (bottom) of 
the stacking order, or just above (below) a designated window: 


window.1lift() 
window. lift (otherwin) 
window. lower () 
window. lower (otherwin) 


AE. Tkinter uses the name 1ift since raise Is a reserved keyword in 
= Python. 


Why do you need to pass a window to get the stacking order? 
Stacking order applies not only for toplevel windows, but for any 
sibling widgets (those with the same parent). If you have several 
widgets gridded together but overlapping, you can raise and lower 
them relative to each other: 


from tkinter import * 
from tkinter import ttk 

root = Tk() 

little = ttk.Label (root, text="Little") 

bigger = ttk.Label (root, text='Much bigger label") 
little.grid(column=0, row=0) 
bigger.grid(column=0, row=0) 

root.after(2000, lambda: little.lift()) 
root.mainloop () 


https://tkdocs.com/code/stackorder.py 


XL. This uses timer events, which we covered in the event loop chapter. 
The after command schedules a script to run at a certain number of 
milliseconds in the future, but leaves the event loop to continue. 


Screen Information 


We've previously used the winfo command to find out information 
about specific widgets. It can also provide information about the 
entire display or screen. As usual, see the winfo command reference 
for full details. 


[3 https://tkdocs.com/man/winfo 


For example, you can determine the screen's color depth (how many 
bits per pixel) and color model (usually truecolor On modern 
displays), it's pixel density, and resolution. 


print("coelor depth="-+ str(root.winto screendepth()}+ " (" + 
root.winfo screéenvisual() + ™)™) 


prant (“pixels per ianch=" > Str(root.winto pixsis( 11") )) 
print ("width=",. str (root.winto scresnwidth({)) + " height=", 
str (root.winfo screenheight () ) ) 


Multiple Monitors 


While normally you shouldn't have to pay attention to it, if you do 
have multiple monitors on your system and want to customize things 
a bit, there are some tools in Tk to help. 

First, there are two ways that multiple monitors can be 
represented. The first is with logically separate displays. This is often 
the case on X11 systems, though it can be changed, e.g., using the 
xrandr system utility. A downside of this model is that once a window 
is created on a screen, it can't be moved to a different one. You can 
determine the screen that a Tk window is running on, which looks 
something like :0.0 (an X11-formatted display name). 


root.winfo screen () 


When first creating a toplevel you can specify the screen it should be 
created on using the screen configuration option. 


AX. Different monitors may have different resolutions, color depths, etc. 
You'll notice that all the screen information calls we just covered are 
methods invoked on a specific widget. They will return information about 

whatever screen that window Is located on. 


Alternatively, multiple monitors can also be represented as one big 
virtual display, which is the case on macOS and Windows. When you 
ask for information about the screen, Tk will return information on the 
primary monitor. For example, if you have two Full HD monitors side- 
by-side, the screen resolution will be reported as 1920 x 1080, not 
3840 x 1080. This is probably a good thing; it means that if we're 
positioning or sizing windows, we don't need to worry about multiple 
monitors, and everything will just show up correctly on the primary 
monitor. 

What if a user moves a window from the primary monitor to a 
different one? If you ask for its position, it will be relative to the 


primary monitor. So in our side-by-side FHD monitor setup, if you call 
the winfo x method on a window positioned near the left edge of a 
monitor, it might return 100 (if it's on the primary monitor), -18 20 (if it's 
on a monitor to the left of the primary monitor), or 2020 (if it's on a 
monitor to the right of the primary monitor). You can still use the 
geometry method we saw a bit earlier to position the window on a 
different monitor, even though the geometry specification may look a 
bit odd, e.g., +-1820+100. 

You can find out approximately how large the entire display is, 
spanning multiple monitors. To do so, check a toplevel widget's 
maximum size, i.e., how large the user can resize it (you can't do this 
after you've already changed it, of course). This may be a bit smaller 
than the full size of the display. For example, on macOS, it will be 
reduced by the size of the menubar at the top of the screen. 


root.wm_maxsize() 


11.3. Dialog Windows 


Dialog boxes are a type of window used in applications to get some 
information from users, inform them that some event has occurred, 
confirm an action, and more. The appearance and usage of dialog 
boxes are usually quite specifically detailed in a platform's style 
guide. Tk comes with several dialog boxes built-in for common tasks. 
These help you conform to platform-specific style guidelines. 


Selecting Files and Directories 


Tk provides several dialogs to let users select files or directories. On 
Windows and macOS, these invoke the underlying operating system 
dialogs directly. The "open" variant on the dialog is used when you 
want users to select an existing file (like in a File | Open... menu 
command), while the "save" variant is used to choose a file to save 
into (usually used by the File | Save As... menu command). 


from tkinter import filedialog 


filename = filedialog.askopenfilename () 
filename = filedialog.asksaveasfilename () 
dirname = filedialog.askdirectory () 


All of these commands produce modal dialogs. This means that the 
commands will not complete until a user submits the dialog. These 
commands return the full pathname of the file or directory a user has 
chosen, or an empty string if a user cancels out of the dialog. 


macOS Windows Linux 


Directory: /media/sf_vboxshare/tkdocs-examples | | 


1@ out country .py f2m.n 
|) .0s_s1 country.rb f2m.ti 


Open file dialogs. 
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Choose directory dialogs. 


Various options can be passed to these dialogs, allowing you to set 
the allowable file types, initial directory, default filename, and many 
more. These are detailed in the getOQpenFile (includes getSaveFile) 
and chooseDirectory reference manual pages. 


[3 https://tkdocs.com/man/getOpenFile 
[3 https://tkdocs.com/man/chooseDirectory 
Selecting Colors 


Another modal dialog lets users select a color. It will return a color 
value, €.g. #££62b8. The dialog takes an optional initialcolor option 
to specify an existing color, i.e., that users might want to replace. 
More information is available in the chooseColor reference manual 
pages. 

[3 https://tkdocs.com/man/chooseColor 


from tkinter import colorchooser 
colorchooser.askcolor (initialcolor='#ff0000") 
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Choose color dialogs. 


Selecting Fonts 


Tk 8.6 added support for another system dialog: a font chooser. While 
the file dialogs and color chooser were modal dialogs, that block until 
the dialog is dismissed and then return a result, the font chooser 
doesn't work like that. 


Q As the font chooser isn't available in Tk 8.5, if your code needs to 
support older Tk versions, you'll need to take that into account. 
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Font chooser dialogs. 


While the system font dialog is modal on some platforms, e.g., 
Windows, that's not the case everywhere. On macOS, the system 
font chooser works more like a floating tool palette in a drawing 
program, remaining available to change the font for whatever text is 
selected in your main application window. The Tk font dialog API has 
to accommodate both models. To do so, it uses callbacks (and virtual 
events) to notify your application of font changes. Additional details 
can be found in the fontchooser reference manual pages. 


[3 https://tkdocs.com/man/fontchooser 


To use the font dialog, first provide it with an initial font and a callback 
which will be invoked when a font is chosen. For illustration, we'll 
have the callback change the font on a label. 


1 = ttk.Label (root, text="Hello World", font="helvetica 24") 
l.grid(padx=10, pady=10) 


def font changed (font) < 


l['font'] = font 
root.tk.call('tk', 'fontchooser', 'configure', '-font', 
"helvetica 24", "command", rootl.register (font changed) ) 
root.tk.call('tk', 'fontchooser', 'show') 


Tkinter has not yet added a convenient way to use this new dialog, so 
this example code uses the Tcl API directly. You can see the latest 
work towards a proper Python API and download code at 
[bugs.python.org/issue28694]. 


You can query or change the font that is (or will be) displayed in the 
dialog at any time. 


Next, put the dialog onscreen via the show method. On platforms 
where the font dialog is modal, your program will block at this point 
until the dialog is dismissed. On other platforms, show returns 
immediately; the dialog remains onscreen while your program 
continues. At this point, a font has not been chosen. There's also a 
hide method to remove it from the screen (not terribly useful when the 
font dialog is modal). 


root.tk.call('tk', 'fontchooser', 'show') 
root.tk.call('tk', 'fontchooser', 'hide') 


If the font dialog was modal, and the user chose a font, the dialog 
would have invoked your callback, passing it a font specification. If 
they cancelled out of the dialog, there'd be no callback. When the 
dialog isn't modal, and the user chooses a font, it will invoke your 
callback. A <<TkFontchooserFontChanged>> virtual event is also 
generated; you can retrieve the current font via the dialog's font 
configuration option. If the font dialog is closed, a 
<<TkFontchooserVisibility>> virtual event is generated. You can also 
find out if the font dialog is currently visible onscreen via the visible 
configuration option (though changing it is an error; use the show and 
hide methods instead). 


Because of the significant differences between them, providing a good 

user experience on all platforms takes a bit of work. On platforms where 

the font dialog is modal,it's likely to be invoked from a button or menu 
item that says, @.g., Font.... On other platforms, the button or menu item 
should toggle between snow Fonts and Hide Fonts. 


If you have several text widgets in your application that can be given different 
fonts, when one of them gains focus, it should update the font chooser with its 
current font. This also means that a callback from the font dialog may apply to a 
different text widget than the one you initially called snow from! Finally, be aware 
that the font chooser itself may gain the keyboard focus on some platforms. 


@ As of Tk 8.6.10, there are a few bugs in the font chooser on various 
platforms. Here's a quick rundown including workarounds: 


* on macOS, if you don't provide a font via the font configuration option, 
your Callbacks won't be invoked = always provide an initial font 


¢ on X11, if you don't provide values for all configuration options, those you 
don't include will be reset to their default values > whenever you change 
any option, change all of them, even if it's just to their current value 


¢ on X11, the font dialog includes an appiy button when you provide a 
callback, but omits it when you don't (and just watch for virtual events); 
however, other bugs mean those virtual events are never generated > 
always provide a command callback 


¢ on Windows, you can also leave off the appiy button by not providing a 
callback; while virtual events are generated on font changes, the font 
configuration option is never updated => always provide a command 
callback, and hold onto the font yourself, rather than trying to ask the font 
dialog for it later 


¢ on Windows, a font change virtual event is not generated if you change 
the font configuration option in your code, though it is on macOS and X11 
= take any necessary actions when you change the font in your code 
rather than in a virtual event handler 


Because of the differences between platforms and the various bugs, testing is 
far more important when using the font chooser than the other system dialogs. 


Alert and Confirmation Dialogs 


Many applications use various simple modal alerts or dialogs to notify 
users of an event, ask them to confirm an action, or make another 
similar choice via clicking on a button. Tk provides a versatile 
"message box" that encapsulates all these different types of dialogs. 


from tkinter import messagebox 
messagebox.showinfo (message='Have a good day') 
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Simple message boxes. 


messagebox.askyesno ( 
message='Are you sure you want to install SuperVirus?' 
icon='gquestion' title='Install') 
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Example message boxes. 


Like the previous dialogs that we've seen, these are modal and return 
the result of a user's action to the caller. Rather than using a type 
option, Tkinter uses a different method name for each type of dialog. 
The return values vary with the method: 


showinfo: 


=> ok 


showwarning: 


=> ok 


showerror: 


as 


as 


as 


as 


as 


=> ok 
kokcancel: 

= True (on ok) or False (on cancel) 
kyesno: 

= True (ON yes) Or False (on no) 
kKretrycancel : 


= True (on retry) or False (on cancel) 
kquestion: 


=> yes or no 


kyesnocancel: 
= True (ON yes), False (ON NO), OF None (On cancel) 


@ Admittedly, the Tkinter messagebox API isn't the most consistent. It mixes 


return types (strings or booleans), there is some duplication (askyesno 
and askquestion), and one underlying dialog type (abortretryignore) IS 


omitted. 


The full list of possible options is shown here: 


Message: 


The main message displayed inside the alert. 


detail: 


A secondary message (if needed). 
title: 

Title for the dialog window. Not used on macOS. 
1¢con’ 

Icon, one of info (default), error, question Of warning. 
default: 


Default button, e.g. ok OF cancel for a okcancel dialog. 
parent: 


Window of your application this dialog is being posted for. 


Additional details can be found in the reference manual. 


[3 https://tkdocs.com/man/messageBox 


These new messagebox dialogs replace the older tk dialog command, 


‘mmms Which does not comply with current platform user interface conventions. 
Rolling YourOwn 


If you need to create your own modal dialogs, there are a few things 
you'll need to take care of. We've covered most of them earlier in the 
chapter, e.g. setting up window styles, positioning the window, etc. 

First, you need to ensure that users can only interact with your 
dialog. You can use grab set to do this. 

If you want your dialog function to block your application (i.e., the 
call to create the dialog shouldn't return until the dialog is dismissed), 
this is also possible. There's no reason you'd need to do this, as you 
can respond to callbacks, event bindings, etc. while running the 
normal event loop, destroy the dialog and move on. 

This somewhat cryptic example includes the main steps needed to 
create a modal dialog. 


ttk. Entry (root) .grid() # something to interact with 
def dismiss (): 

dig.grab. release () 
dlg.destroy() 


dlg = Toplevel (root) 
ttk.Button(dlg, text="Done", command=dismiss) .grid() 
dlg.protocol ("WM DELETE WINDOW", dismiss) # intercept close 
button 


dlg.transient (root) # dialog window is related to main 
dlg.wait_visibility() # can't grab until window appears, so we 
wait 

dlg.grab set () # ensure all input goes to our window 
dlg.wait window () # block until window is destroyed 


https://tkdocs.com/code/dialog.py 


Application code blocking like this is an example of running a nested 
event loop that we generally recommend against, though it may be 
more convenient in certain circumstances. 


Tkinter's standard library includes a simpledialog module that helps 
with building your own dialogs. Because it uses the classic Tk 
widgets rather than the newer themed widgets, we don't recommend 
using it directly. However, it does illustrate how to use some of the 
techniques for making dialogs behave that we just covered. 


12. Organizing Complex 
Interfaces 


If you have a complex user interface, you'll need to find ways to 
organize it that don't overwhelm your users. There are several 
different approaches to doing this. Both general-purpose and 
platform-specific human interface guidelines are good resources 
when designing your user interface. 

When we talk about complexity in this chapter, we don't mean the 
underlying technical complexity of how the program is implemented. 
Instead, we mean how it's presented to users. A user interface can 
be pulled together from many different modules, built from hundreds 
of widgets combined in a deeply nested hierarchy, but that doesn't 
mean users need to perceive it as complex. 


Multiple windows 


One benefit of using multiple windows in an application can be to 
simplify the user interface. Done well, it can require users to focus 
only on the contents of one window at a time to complete a task. 
Forcing them to focus on or switch between several windows can 
also have the opposite effect. Similarly, showing only the widgets 


relevant to the current task (i.e., via gria) can help simplify the user 
interface. 


White space 


If you do need to display a large number of widgets onscreen at the 
same time, think about how to organize them visually. We've seen 
how grid makes it easy to align widgets with each other. White 
space is another useful aid. Place related widgets close to each 
other (possibly with an explanatory label immediately above) and 
separate them from other widgets by white space. This helps users 
organize the user interface in their own minds. 


Q The recommended amount of white space around different widgets, 
between groups of widgets, around borders, etc. is highly platform- 
specific. While you can do an adequate job without worrying about 

exact pixel numbers, if you want a highly polished user interface, you'll need to 

tune this for each platform. 


12.1. Separator 


Mr. ttk.Separator 
« 


[3 https://tkdocs.com/man/ttk_separator 


A second approach to grouping widgets in one display is to place a 
thin horizontal or vertical rule between groups of widgets; often, this 
can be more space-efficient than using white space, which may be 
relevant for a tight display. Tk provides a simple separator widget for 
this purpose. 
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Separator widgets. 


Separators are created using the ttk.Separator Class: 


s = ttk.Separator (parent, orient=HORIZONTAL) 


The orient option may be specified as either horizontal OF vertical. 


12.2. Label Frames 


fh ttk.Labelframe 


[3 https://tkdocs.com/man/ttk_labelframe 


A labelframe widget, also commonly known as a group box, 
provides another way to group related components. It acts like a 
normal ttk::frame, in that it contains other widgets that you grid 
inside it. However, it is visually set off from the rest of the user 
interface. You can optionally provide a text label to be displayed 
outside the labelframe. 
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Labelframe widgets. 


Labelframes are created using the ttk.Labelframe Class: 


lf = ttk.Labelframe (parent, text='Label') 


12.3. Paned Windows 


ED ite Hanedwindow 


[3 https://tkdocs.com/man/ttk_panedwindow 


A panedwindow widget lets you stack two or more resizable 
widgets above and below each other (or to the left and right). Users 
can adjust the relative heights (or widths) of each pane by dragging 
a sash located between them. Typically the widgets you're adding to 
a panedwindow will be frames containing many other widgets. 


macOS Windows Linux 
Pane Pane Pane3 Panel Pane2 Pane3 Panel. -Pane2. -Pane3 
Panel Panel Panel 
Pane2 Pane2 Pane2 


Panedwindow widgets (shown here managing several labelframes). 


Panedwindows are created using the ttk.Panedwindow Class: 


p = ttk.Panedwindow(parent, orient=VERTICAL) 
# two panes, each of which would get widgets gridded into it: 


fl = ttk.Labelframe(p, text='Panel', width=100, height=100) 
£2 = ttk.Labelframe(p, text='Pane2', width=100, height=100) 
p.add(f1) 
p.add(f2) 


A panedwindow is either vertical (its panes are stacked vertically 
on top of each other) or horizontal. Importantly, each pane you add 
to the panedwindow must be a direct child of the panedwindow itself. 


Calling the aaa method adds a new pane at the end of the list of 
panes. The insert position subwindow method allows you to place 
the pane at the given position in the list of panes (0..n-1). If the pane 
is already managed by the panedwindow, it will be moved to the new 
position. You can use the forget subwindow to remove a pane from 
the panedwindow (you can also pass a position instead of a 
subwindow). 

You can assign relative weights to each pane so that if the overall 
panedwindow resizes, certain panes will be allocated more space 
than others. As well, you can adjust the position of each sash 
between items in the panedwindow. See the command reference for 
details. 
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12.4. Notebook 


fr ttk .Notebook 
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A notebook widget uses the metaphor of a tabbed notebook to let 
users switch between one of several pages, using an index fab. 
Unlike with paned windows, users only see a single page (akin to a 
pane) at a time. 


macOs Windows Linux 
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Notebook widgets. 


Notebooks are created using the ttk.Notebook Class: 


n = ttk.Notebook (parent) 

fl = ttk.Frame(n) # first page, which would get widgets 
gridded into it 

£2 = ttk.Frame (n) # second page 


n.add(fl, text='One') 
n.add(f2, text='Two') 


The operations on tabbed notebooks are similar to those on 
panedwindows. Each page is typically a frame and again must be a 
direct child (subwindow) of the notebook itself. A new page and its 
associated tab are added after the last tab with the ada subwindow ? 
option value...? method. The text tab option sets the label on the 
tab; also useful is the state tab option, which can have the value 
normal, disabled (not selectable), OF hidden. 


To insert a tab at somewhere other than the end of the list, use 
the insert position subwindow ?option value...?, and to remove a 
given tab, use the forget method, passing it either the position (0..n- 
1) or the tab's subwindow. You can retrieve the list of all subwindows 
contained in the notebook via the tabs method. 

To retrieve the subwindow that is currently selected, call the 
select method, and change the selected tab by passing it either the 
tab's position or the subwindow itself as a parameter. 

To change a tab option (like the text label on the tab or its state), 
you can use the tab(tabid, option=value) method (where tabid is 
again the tab's position or subwindow); omit the =vaiue to return the 
current value of the option. 

Notebook widgets generate a <<NotebookTabChanged>> virtual 
event whenever a new tab is selected. 

Again, there are a variety of less frequently used options and 
commands detailed in the command reference. 
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13. Fonts, Colors, Images 


This chapter describes how Tk handles fonts, colors, and images. We've 
touched on all of these before, but here we'll provide a more in-depth 
treatment. 


13.1. Fonts 


Tk's label widget allows you to change the font used to display text via 
the font configuration option. The canvas and text widgets, covered in 
the following chapters, also allow you to specify fonts. Other themed 
widgets that display text may not have a font configuration option, but 
their fonts can be changed using styles. 


AXE. We'll cover styles in detail later. In essence, they replace the old way of 
tweaking multiple configuration options on individual widgets. Instead, 
fonts, colors, and other settings that control appearance can be bundled 

together in a style. That style can then be applied to multiple widgets. It's akin to 
the difference between hardcoding display-oriented markup inside HTML pages vs. 
using CSS to keep display-specific information separate. 


As with many things in Tk, the default fonts are usually a good choice. If 
you need to make changes, this section shows you the best way to do 
so, using named fonts. Tk includes named fonts suitable for use in all 
different components of your user interface. They take into account the 
conventions of the specific platform you're running on. You can also 
specify your own fonts when you need additional flexibility. 

The font command reference provides full details on specifying fonts, 
as well as other font-related operations. 
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Many older Tk programs hardcoded fonts, using either the "family size 
style" format we'll see below, X11 font names, or the older and more arcane 
X11 font specification strings. These applications looked increasingly dated 
as platforms evolved. Worse, fonts were often specified on a per-widget basis, 
leaving font decisions spread throughout the code. Named fonts, particularly the 
standard fonts that Tk provides, are a far better solution. Reviewing and updating 
font decisions is an easy and important change to make in any existing 
applications. 


UPGRADE 
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Standard Fonts 


Each platform defines specific fonts that should be used for standard 
user interface elements. Tk encapsulates many of these decisions into a 
standard set of named fonts. They are available on all platforms, though 
the exact font used will vary. This helps abstract away platform 
differences. Of course, the standard widgets use these named fonts. 
The predefined fonts are: 


TkDefaultFont: 

Default for items not otherwise specified. 
TkTextFont: 

Used for entry widgets, listboxes, etc. 
TkFixedFont: 

A standard fixed-width font. 

TkMenuFont: 

The font used for menu items. 
TkHeadingFont: 
Font for column headings in lists and tables. 
TkCaptionFont: 
A font for window and dialog caption bars. 
TkSmallCaptionFont: 

A smaller caption font for tool dialogs. 
TkIconFont: 

A font for icon captions. 

TKEeOLtipFont: 


A font for tooltips. 


Platform-Specific Fonts 


Tk provides additional named fonts to help you comply with less 
common situations on specific platforms. Individual platform guidelines 
detail how and where these fonts should be used. These fonts are only 
defined on specific platforms. You'll need to take that into account if your 
application is portable across platforms. 

Tk on X11 recognizes any valid X11 font name (see, e.g., the 
xlsfonts Command). However, these can vary with the operating 
system, installed software, and the configuration of the individual 
machine. There is no guarantee that a font available on your X11 
system has been installed on any other X11 system. 

On Windows, Tk provides named fonts for all the fonts that can be set 
in the "Display" Control Panel. It recognizes the following font names: 
system, ansi, device, systemfixed, ansifixed, and oemfixed. 


On macOS, the Apple Human Interface Guidelines (HIG) specifies a 
number of additional fonts. Tk recognizes the following names: 
systemSystemFont, systemSmallSystemFont, systemApplicationFont, 


systemViewsFont, systemMenultemFont, systemMenultemCmdKeyFont, 


systemPushButtonFont, systemAlertHeaderFont, systemMiniSystemFont, 


systemDetailEmphasizedSystemFont, systemEmphasizedSystemFont, 


systemSmallEmphasizedSystemFont, systemLabelFont, 


systemMenuTitleFont, systemMenulItemMarkFont, systemWindowTitleFont, 


systemUtilityWindowTitleFont, systemToolbarFont, and 


systemDetailSystemFont. 


Working with Named Fonts 


Tk provides several operations that help you work with named fonts. 
You can start by getting a list of all the currently defined named fonts. 


from tkinter import font 
font.names () 


You can find out the actual system font represented by an abstract 
named font. This consists of the family (€.g., Times OF Helvetica), the 
size (in points if positive, in pixels if negative), the weight (normal or 
bold), the slant (roman Or italic), and boolean attributes for underline 
and overstrike. You can find out the font's metrics (how tall characters 
in the font can be and whether it is monospaced), and even measure how 
many pixels wide a piece of text rendered in the font would be. 


>>> from tkinter import font 
>>> £ = font.nametofont(' TkTextFont' ) 
>>> £.actual () 


{'family': '.AppleSystemUIFont', 'size': 13, 'weight': 'normal', 
"slant': 'roman', ‘underline': 0, 'overstrike': 0} 

>>> £.metrics () 

{'ascent': 13, 'descent': 3, 'linespace': 16, 'fixed': 0} 

>>> £.measure(' The quick brown fox' ) 

124 


Tkinter provides a Font Class to hold information about a named font. 
You can create an instance of this class from the name of a font using 
the nametofont function. When you use named fonts in your application 


(e.g., via a label's font configuration option), you can supply either the 
font name (as a string) or a Font instance. 


Trying these in an interactive shell and got an error? Even though we're not 
displaying anything onscreen, you need to initialize Tk before using the 
various font functions. 


You can also create your own fonts, which can then be used exactly like 
the predefined ones. To do so, choose a name for the font and specify 
its font attributes as above. 


from tkinter import font 
highlightFont = font.Font (family='Helvetica', 
name='appHighlightFont', size=12, weight='bold') 

ttk.Label (root, text='Attention!', font=highlightFont) .grid() 


If you don't supply a name, Tkinter will generate one, which you can 
retrieve via font.name OF str (font). It's usually best to supply one. 

The family attribute specifies the font family. Tk ensures the names 
Courier, Times, ANd Helvetica are available, though they may be 
mapped to an appropriate monospaced, serif, or sans-serif font). Other 
fonts installed on your system can be used, but the usual caveats about 
portability apply. You can get the names of all available families with: 


ont.families() 


You can change the attributes of a named font using its configure method. 
You might do this in response to menu options allowing users to zoom in or 
out, i.e., increasing or decreasing font sizes. 


Font Descriptions 


Another way to specify fonts is via a list of attributes. starting with the 
font family, and then optionally includes a size, and one or more style 
options. Some examples of this are Helvetica, Helvetica 12, Helvetica 
12 bold, aNd Helvetica 12 bold italic. These font descriptions can be 
used anywhere you'd use a named font, e.g., a font configuration 
option. 


In general, switching from font descriptions to named fonts is advisable to isolate 
font differences in one location in the program. 
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13.2. Colors 


As with fonts, there are various ways to specify colors. Full details can 
be found in the colors command reference. 
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In general, Tk widgets default to the right colors for most situations. If 
you'd like to change colors, you'll do so via widget-specific commands or 
options, e.g., the label's foreground and background configuration 
options. For most themed widgets, color changes are specified through 
styles, not by changing the widget directly. 

You can specify colors via RGB, as you would in HTML or CSS, e.g. 
#3FF Or #FF016a. Tk also recognizes names such aS red, black, grey50, 
light blue, etc. 


AX. Tk recognizes the standard names for colors defined by X11. You can find 
a complete list in the command reference (noted above). 


As with fonts, both macOS and Windows specify many system-specific 
abstract color names (again, see the reference). The actual color these 
correspond to may depend on system settings and can change over 
time, e.g., dark mode, text highlight colors, default backgrounds. 

If needed, you can find the RGB values (each between 0 and 65535) 
for a color using the winfo_rgb method on any widget. 


root.winfo rgb('red') 


Q It should probably go without saying, but restraint in the use of colors is 
highly advisable! 


13.3. Images 


We've seen the basics of how to use images already, displaying them in 
labels or buttons, for example. We create an image object, usually from 
a file on disk. 


imgobj = PhotoImage(file='myimage.gif') 
label['image'] = imgobj 


Out of the box, Tk 8.5 includes support for GIF and PPM/PNM images. 
Tk 8.6 added PNG to this short list. However, there is a Tk extension 
library called tmg, which adds support for many others: BMP, XBM, XPM, 
JPEG, PNG (if you're using 8.5), TIFF, etc. Though not included directly 
in the Tk core, Img is usually included with other packaged distributions 
(e.g., ActiveTcl). 

Instead of using Tk's Img extension, Tkinter uses a made-for-Python 
image library called pri (Python Imaging Library). More specifically, we'll 
use a more up-to-date fork of PIL called pillow. As it doesn't come 
bundled with Python, you'll normally need to install it. You should be 
able to do so via, @.g., pip install Pillow. 


from PIL import ImageTk, Image 
myimg = ImageTk.PhotoImage (Image.open('myimage.png") ) 


The ImageTk.PhotoImage Call provides a drop-in replacement for Tk's 
PhotoImage but supports the broader range of image types. 

Tk's images are actually quite powerful and sophisticated and provide 
a wide variety of ways to inspect and modify images. You can find out 
more from the image command reference and the photo command 
reference. 
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The types of multi-color images we've seen here are referred to in Tk as 
photo images. Tk also provides a second type of images, two-bit bitmap 
images, which were widely used in the '90s when most Unix workstations 
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used quite large (compared with PCs) monitors, but they were only black and 
white. Needless to say, color is mostly de rigueur these days, so updating to full- 
color images for icons and so on is highly advisable. Though in what some may 
consider retro-styling, some flat and material design schemes have returned to 
black and white. Plus ¢a change... 


14. Canvas 


mel Canvas 
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A canvas widget manages a 2D collection of graphical objects 
lines, circles, text, images, other widgets, and more. Tk's canvas is 
an incredibly powerful and flexible widget, and truly one of Tk's 
highlights. It is suitable for a wide range of uses, including drawing or 
diagramming, CAD tools, displaying or monitoring simulations or 
actual equipment, and building more complex widgets out of simpler 
ones. 

Note: Canvas widgets are part of the classic Tk widgets, not the 
themed Tk widgets. 
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Canvas widgets. 


Canvas widgets are created using the canvas Class: 


canvas = Canvas(parent, width=500, height=400, 
background='gray7/5"') 


You'll often provide a width and height, either in pixels or any of the 
other standard distance units. As always, you can ask the geometry 
manager to expand it to fill the available space in the window. You 
might provide a default background color for the canvas, specifying 
colors in any of the ways you learned about in the last chapter. 
Canvas widgets also support other appearance options like relief 
and borderwidth that we've used before. 

Canvas widgets have a tremendous number of features, and we 
won't cover everything here. Instead, we'll start with a simple 
example, a freehand sketching tool, and incrementally add new 
pieces to it, each showing another new feature of canvas widgets. 


14.1. Creating Items 


When you create a new canvas widget, it is essentially a large 
rectangle with nothing on it, truly a blank canvas in other words. To 
do anything useful with it, you'll need to add items to it. There are a 
wide variety of different types of items you can add. Here, we'll add a 
simple line item to the canvas. 

To create a line, you need to specify its starting and ending 
coordinates. Coordinates are expressed as the number of pixels 
away from the top-left corner, both horizontally and vertically, i.e. 
(x,y). The pixel at the top-left corner, Known as the origin, has 
coordinates (0,0). The "x” value increases as you move to the right 
and the "y” value increases as you move down. A line is described 
by two points, which we'd refer to as (x0,y0) and (x7,y1). This code 
creates a line from (10,5) to (200,50): 


canvas.create line(10, 5, 200, 50) 


The create line method returns an item id (an integer) that uniquely 
refers to this item. We'll see how it can be used shortly. Often, we 
don't need to refer to the item later and can ignore the returned id. 


A Simple Sketchpad 


Let's start our simple sketchpad example. For now, we'll implement 
freehand drawing on the canvas with the mouse. We create a 
canvas widget and attach event bindings to it to capture mouse 
clicks and drags. When the mouse is first pressed, we'll remember 
that location as the "start" coordinates of our next line. As the mouse 
is moved with the mouse button held down, we create a line item 
from this "start" position to the current mouse location. This current 
location becomes the "start" position for the next line item. Every 
mouse drag creates a new line item. 


from tki 


net 


from tki 


net 


* 


ttk 


er import 
er import 


def savePosn(event): 


glob 
last 


al 
xy 


lastx, lasty 
lasty = event.x, event.y 


def addLine (event): 
canvas.create line((lastx, lasty, event.x, 
savePosn (event) 


rool 


root 


Canvas = 


canvas.grid(column=0, row=0, sticky=(N, W, E, S)) 


C 


t = Tk() 
root.columnconfigure(0, weight=1) 
t.rowconfigure(0, weight=1) 


anvas (root) 


canvas.bind("<Button-1>", savePosn) 
canvas.bind("<Bl-Motion>", addLine) 


root.mainloop () 
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Again, in this simple example, we're using global variables to store 
the start position. In practice, we'd encapsulate all of this in a Python 
class. Here's one way we could do that. Note that this example 
creates a subclass of canvas, which is treated like any other widget in 
the code. We could have equally well used a standalone class, as 


we did with the "feet to meters" example. 


from tki 


from tki 


class Sk 
def 


def 


def 


* 


nter import 

nter import ttk 

etchpad (Canvas) : 

_ init. (self, parent, **kwargs) : 
super(). init (parent, **kwargs) 
self. bind("<Button-l1>", selft.save posn) 
Sself.bind("<Bl-Motions", self.add line) 
save_posn(self, event): 


se 


add_line(self, event): 
lf,ereate line ((self.lastx, self.lasty, 


se 


lf.lastx, self.lasty = event.x, event. 


event.y)) 


event.xX, 


event.y)) 
Sselr Save posn (event) 


t = Tk() 
root.columnconfigure(0, weight=1) 
t.rowconfigure(0, weight=1) 


sketch = Sketchpad (root) 
sketch.grid(column=0, row=0, sticky=(N, W, E, S)) 


root.mainloop() 


https://tkdocs.com/code/sketcho.py 


Try it out - drag the mouse around the canvas to create your 
masterpiece. 


Item Attributes 


When creating items, you can also specify one or more attributes for 
the item, affecting how it is displayed. For example, here we'll specify 
that the line should be red and three pixels wide. 


canvas.create line(10, 10, 200, 50, fill="red", width=3) 


The exact set of attributes will vary according to the type of item. 
Some commonly used ones are: 


fill: 
color to draw the object 
width: 
line width of the item (or its outline) 


outline: 
for filled shapes like rectangles, the color to draw the item's 


outline 
dash: 


draw a dashed line instead of a solid one, e.g., 2 4 6 4 
alternates short (2 pixels) and long (6 pixels) dashes with 4 


pixels between 
stipple: 


instead of a solid fill color, use a pattern, typically gray75, gray50, 


gray25, OF gray12; stippling is currently not supported on macOS 
state: 


assign a state of normal (default), disabled (item event bindings 


are ignored), Or hidden (removed from display) 
disabledfill, disabledwidth, a3 


if the item's state is set to disabled, the item will display using 


these variants of the usual attributes 
activefill, activewidth, 


when the mouse pointer is over the item, it will display using 
these variants of the usual attributes 


Q If you have canvas items that change state, creating the item with both 
the regular and disabled attribute variants can simplify your code. You 
simply need to change the item's state, rather than writing code to 
change multiple display attributes. The same applies to the active*. Both 
encourage a more declarative style that can remove a lot of boilerplate code. 


Akin to Tk widgets, changing attributes for canvas items after we've 
already created them is easily accomplished. 


id = canvas.create line(0, 0, 10, 10, fill='red"') 
canvas.itemconfigure(id, fill='blue', width=2) 
Item Types 


Canvas widgets support a wide variety of item types. 
Line 


Our sketchpad created simple line items, each a single segment with 
a start point and an end point. Lines items can also consist of 
multiple segments. 


canvas.create line(10, 10, 200, 50, 90, 150, 50, 80) 


Lines have several interesting additional attributes, allowing for 
drawing curves, arrows, and more. 


arrow: 
place an arrowhead at the start (first), end (iast), or both ends 


(both); default is none 
arrowshape: 


allows changing the appearance of any arrowheads 
capstyle: 
for wide lines without arrowheads, this controls how the end of 
lines are drawn; one of butt (default), projecting, OF round 
joinstyle: 
for wide lines with multiple segments, this controls drawings of 


each vertex; one of rouna (default), bevel, Or miter 
smooth: 


if specified as true (Or bezier), draws a smooth curve (via 
quadratic splines) between multiple segments rather than using 
straight lines; raw specifies a different type of curve (cubic 
splines) 

splinesteps: 
controls the smoothness of curved lines, i.e., those with the 
smooth option set 


Rectangle 


Rectangles are specified by the coordinates of opposing corners, 
e.g., top-left and bottom-right. They can be filled in (via ¢i11) with 
one color, and the outline given a different color. 


Canvas.create rectangle (10, 10, 200, 30, fill='"red’, 
outline='blue') 


Oval 


Ovals items work exactly the same as rectangles. 


canvas.create oval(10, 10, 200, 150, fill='red', 
outline='blue') 


Polygon 


Polygon items allow you to create arbitrary shapes as defined by a 
series of points. The coordinates are given in the same way as 
multipoint lines. Tk ensures the polygon is "closed," attaching the 
last point to the first if needed. Like ovals and rectangles, they can 
have separate fill and outline colors. They also support the 
joinstyle, smooth, and splinesteps attributes of line items. 


canvas.create polygon(10, 10, 200, 50, 90, 150, 50, 80, 120, 
55, fill='red', outline='blue') 


Arc 


Arc items draw a portion of an oval; think of one piece of a pie chart. 
It's display is controlled by three attributes: 


e start: how far along the oval the arc should start, in degrees (0 
is the 3-o'clock position) 


e The extent: how many degrees "wide" the arc should be, 
positive for counter-clockwise from the start, negative for 
clockwise 


e style: one Of pieslice (the default), arc (draws just the outer 
perimeter), or chord (draws the area between a line connecting 
the start and end points of the arc, and the outer perimeter). 


canvas.create arc(10, 10, 200, 150, fill="yellow', 
outline='black', start=45, extent=135, width=5) 


Image 


Image items can display arbitrary images. By default, the item is 
centered at the coordinates you specify, but this can be changed 
with the anchor option, €.g., nw means the coordinates are where to 
put the top-left of the image. 


myimg = PhotoImage(file='pretty.png') 
Ccanvas.create image(10, 10, image=myimg, anchor='nw') 


There's also a bitmap item type for images having only two colors, 
which can be changed via foreground and background. It's not 
something that would commonly be used these days. 


Text 


Text items can display a block of text. Positioning the text works the 
same as with image items. Specify the text to display using the text 
attribute. All of the text in the item will have the same color (specified 
by the £i11 attribute) and the same font (specified by a font 
attribute). 

The text item can display multiple lines of text if you embed \n in 
the text. Alternatively, you can have the item automatically wrapped 
into multiple lines by providing a width attribute to represent the 
maximum width of a line. The alignment of multiple lines of text can 
be set using the justify attribute, which can be one of iecrt (the 
default), right, Of center. 


Calves. Creece ovel (100, 100, téxt—'s wonderrul. suory', 
anchor='nw', font='TkMenuFont', fill='red') 


Widget 


One of the coolest things you can do with the canvas widget is to 
embed other widgets inside it. This can be a lowly button, an entry 
(think in-place editing of text items), a listbox, a frame itself 
containing a complex set of widgets... anything! Remember when we 
said way back when that a canvas widget could act as a geometry 
manager? This is what we meant. 

Canvas items that display other widgets are known as window 
items (Tk's longstanding terminology for widgets). They are 
positioned like text and image items. You can give them explicit 
width and height attributes; they default to the widget's preferred 


size. Finally, it's important that the widget you're placing on the 
canvas (via the window) attribute be a child widget of the canvas. 


b = ttk.Button(camvas, text='Implode!') 
canvas.create image(10, 10, anchor='nw', window=b) 


Modifying Items 


We've seen how you can modify the configuration options on an item 
its color, width,-etc. There are several other things you can do 
with items. 

To delete items, use the delete method. 

To change an item's size and position, you can use the coords 
method. You supply new coordinates for the item, specified the same 
way as when you first created it. Calling this method without a new 
set of coordinates will return the current coordinates of the item. To 
move one or more items by a particular horizontal or vertical amount 
from their current location, you can use the move method. 

All items are ordered from top to bottom in what's called the 
stacking order. If an item later in the stacking order overlaps an item 
below it, the first item will be drawn on top of the second. The lift 
and lower methods allow you to adjust an item's position in the 
stacking order. 

There are several more operations detailed in the reference 
manual. They describe more ways to modify items and retrieve 
information about them. 


14.2. Event Bindings 


We've already seen that the canvas widget as a whole, like any other 
Tk widget, can capture events using the bind command. 

You can also attach bindings to individual items in the canvas (or 
groups of them, as we'll see in the next section using tags). So if you 
want to know whether or not a particular item has been clicked on, 
you don't need to watch for mouse click events for the canvas as a 
whole, and then figure out if that click happened on your item. Tk will 
take care of all this for you. 

To capture these events, you use a bind command built into the 
canvas. It works exactly like the regular bind command, taking an 
event pattern and a callback. The only difference is you specify the 
canvas item this binding applies to. 


Cativas.tag bind(id;,; "<1>", «~.8) 


Q Note the difference between the item-specific tag bina method and the 
widget-level bina method. 


Let's add some code to our sketchpad example to allow changing 
the drawing color. We'll first create a few different rectangle items, 
each filled with a different color. We'll then attach a binding to each 
of these. When they're clicked on, they'll set a global variable to the 
new drawing color. Our mouse motion binding will look at that 
variable when creating the line segments. 


color = "black" 

def setColor(newcolor): 
global color 
color = newcolor 


def addLine (event): 
global lastx, lasty 
canvas.create line(({lastx, lasty, event.x, event.y), 
fill=color) 
lastx, lasty = event.x, event.y 


id = canvas.create rectangle((10, 10, 30, 30), fill="red") 


Canvas.tag bind(id, “<Button-1>", lambda x: setColor ("red") ) 
1d = Canvess.Oreate rectangle( (10; 35, 30, 35), £1 Ll="blue™) 
Canvas.tag bind(id, “<Button=-1>", lambda x: setColor ("blue") ) 
id = Canvas.creéate rectangle ((10, 60, 30, 80), 21 l1="black") 
canvas.tag bind(id, "<Button-1>", lambda x: 


setColor ("black") ) 
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14.3. Tags 


We've seen that every canvas item has a unique id number, but 
there is another very useful and powerful way to refer to items on a 
canvas, and that is using tags. 

A tag is just an identifier of your creation, something meaningful to 
your program. You can attach tags to canvas items; each item can 
have any number of tags. Unlike item id numbers, which are unique 
for each item, many items can have the same tag. 

What can you do with tags? We saw that you can use the item id 
to modify a canvas item (and we'll see soon there are other things 
you can do to items, like move them around, delete them, etc.). Any 
time you can use an item id, you can use a tag. For example, you 
can change the color of all items having a specific tag. 

Tags are a good way to identify certain types of items in your 
canvas (items that are part of a drawn line, items that are part of the 
palette, etc.). You can use tags to correlate canvas items to 
particular objects in your application (for example, tag all canvas 
items that are part of the robot with id #37 with the tag "robot37"). 
With tags, you don't have to keep track of the ids of canvas items to 
refer to groups of items later; tags let Tk do that for you. 

You can assign tags when creating an item using the tags item 
configuration option. You can add tags later with the addtag method, 
or remove them with the atags method. You can get the list of tags 
for an item with the gettags method, or return a list of item id 
numbers having the given tag with the fing command. 

For example: 


>>> c = Canvas (root) 

poem ©.create line (10, 10, 20, 20, tags=("firstline’, 
"drawing')) 

1 

>>> c.create rectangle(30, 30, 40, 40, tags=('drawing")) 
2 


>>> c.addtag('rectangle', 'withtag', 2) 
>>> c.addtag('polygon', '‘withtag', 'rectangle') 
>>> c.gettags (2) 


('drawing', 'rectangle', 'polygon') 
>>> c.dtag(2, 'polygon') 

>>> c.gettags (2) 

('drawing', 'rectangle') 

Per Os.Find withtag (*drawing *) 

(ly 4) 


As you can see, things like witntag will take either an individual item 
or a tag; in the latter case, they will apply to all items having that tag 
(which could be none). The addtag and find have many other 
options, allowing you to specify items near a point, overlapping a 
particular area, etc. 

Let's use tags first to put a border around whichever item in our 
color palette is currently selected. 


def setColor(newcolor): 
global color 
color = newcolor 
canvas.dtag('all', 'paletteSelected') 
canvas.itemconfigure('palette', outline='white') 
canvas.addtag('paletteSelected', 'withtag', 'palette%ts' $% 
color) 
canvas.itemconfigure('paletteSelected', 
outline='#999999') 


id = tanvas.create rectangle((10, 10, 30, 30), £fill="red", 
tags=('palette', 'palettered') ) 

io =] Canvas create rectangle ( (10, 25, 50, So), £2 l1="blGe", 
tags=('palette', 'paletteblue') ) 

id = Canvas.create rectangle ({(10,; 60, 30, 80), fill="black", 
tags=('palette', 'paletteblack', 'paletteSelected') ) 


setColor('black') 
canvas.itemconfigure('palette', width=5) 


Let's also use tags to make the current stroke being drawn appear 
more prominent. When the mouse button is released, we'll return the 
line to normal. 


def addLine (event): 

global lastx, lasty 

canvas.create line((lastx, lasty, event.x, event.y), 
fill=color, width=5, tags='currentline') 


lastx, lasty = event.x, event.y 


def doneStroke (event) : 
canvas.itemconfigure('currentline', width=1) 


canvas.bind("<Bl-ButtonRelease>", doneStroke) 
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14.4. Scrolling 


In many applications, you'll want the canvas to be larger than what 
appears on the screen. You can attach horizontal and vertical 
scrollbars to the canvas in the usual way, via the xview and yview 
methods. 

You can specify both how large you'd like it to be on screen and 
its full size (which would require scrolling to see). The width and 
height configuration options for the canvas widget will request the 
given amount of space from the geometry manager. The 
scrollregion configuration option tells Tk how large the canvas 
surface is by specifying its left, top, right, and bottom coordinates, 
€.g., 0 0 1000 1000. 

You should be able to modify the sketchpad program to add 
scrolling, given what you already know. Give it a try. 

Once you've done that, scroll the canvas down just a little bit, and 
then try drawing. You'll see that the line you're drawing appears 
above where the mouse is pointing! Surprised? 

What's going on is that the global bina command doesn't know 
that the canvas is scrolled (it doesn't know the details of any 
particular widget). So if you've scrolled the canvas down by 50 
pixels, and you click on the top left corner, bind will report that you've 
clicked at (0,0). But we know that because of the scrolling, that 
position should really be (0,50). 

The canvasx and canvasy methods translate the position onscreen 
(which bind reports) into the actual point on the canvas (taking into 
account scrolling). 


e careful if you're adding canvasx and canvasy methods directly to the event 

e binding scripts. You need to watch the quoting and substitutions to 

ensure the conversions are done when the event fires. As always, it's 

better to place that code in a procedure separate from the event 
binding itself. 


Here then, is our complete example. We probably don't want the 
palette to be scrolled away when the canvas is scrolled, but we'll 
leave that for another day. 


from tkinter import 


ct ct 


from tkinter import ttk 

root = Tk() 

h = ttk.Scrollbar (root, orient=HORIZONTAL) 

v = ttk.Scrollbar(root, orient=VERTICAL) 

canvas = Canvas (root, scrollregion=(0, 0, 1000, 1000), 
yscrollcommand=v.set, xscrollcommand=h.set) 
h['command'] = canvas.xview 

v['command'] = canvas.yview 


canvas.grid(column=0, row=0, sticky=(N,W,E,S) ) 
h.grid(column=0, row=1, sticky=(W,E) 
v.grid(column=1, row=0, sticky=(N,S) 
root.grid columnconfigure(0, weight= 
root.grid rowconfigure(0, weight=1) 


) 
) 
1 


) 


lastx, lasty = 0, O 


def xy(event): 

global lastx, lasty 

lastx, lasty = canvas.canvasx(event.x), 
canvas.canvasy (event.y) 


def setColor(newcolor): 
global color 
color = newcolor 
canvas.dtag('all', 'paletteSelected') 
canvas.itemconfigure('palette', outline='white') 
canvas.addtag('paletteSelected', 'withtag', 'palette%Ss' % 
color) 
canvas.itemconfigure('paletteSelected', 
outline='#999999') 


def addLine (event): 
global lastx, lasty 
xX, Y = canvas.canvasx(event.x), canvas.canvasy(event.y) 
canvas.create line((lastx, lasty, x, y), fill=color, 
width=5, tags='currentline') 
lastx, lasty = x, y 


def doneStroke (event): 


canvas.itemconfigure('currentline', width=1) 
canvas.bind("<Button-1>", xy) 
canvas.bind("<Bl-Motion>", addLine) 
canvas.bind("<Bl-ButtonRelease>", doneStroke) 
id = Canvas.create rectangle({(10, 10, 30, 30), fil 
tags=('palette', 'palettered') ) 
Canvas.tag bind (id, "<Button-l>",. lambda x: sebCol 
id. = Canvas.create rectangle ((10,.'35, 30, 33), 211 
tags=('palette', 'paletteblue') ) 
canvas.tag bind(id, "<Button-1>", lambda x: setCol 
id = Gafivas.create rectangle((10, 60, 30, 80), fil 
tags=('palette', 'paletteblack', 'paletteSelected!' 
canvas.tag bind{id, “<Button-l>", lambda x: 
setColor ("black") ) 
setColor('black') 
canvas.itemconfigure('palette', width=5) 


root.mainloop() 
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l="red", 


or ("red") ) 
1="blue", 


or ("blue") ) 
1="black", 
)) 


15. Text 


Pel Text 


« 


[3 https://tkdocs.com/man/text 


A text widget manages a multi-line text area. Like the canvas widget, 
Tk's text widget is an immensely flexible and powerful tool which can 
be used for a wide variety of tasks. It can provide a simple multi-line 
text area as part of a form. But text widgets can also form the basis for 
a stylized code editor, an outliner, a web browser, and much more. 
Note: Text widgets are part of the classic Tk widgets, not the themed 


Tk widgets. 


macOS 


Lorem ipsum dolor sit amet, 


donec a dignissimos orci non 
nonummy tristique sit metus, 
velit odio at odio ridiculus. 


Ut dui libero 


eget, varius scelerisque mauris 
erat a. Sit morbi et purus class 


id ante quis 


fringilla tortor t<) suspendisse 


Sinem naeiava wv hanno 1 Li ameanvnay 


Windows 


Lorem [Ei eeeeeen 
lame d 


, Gdonec a dignissimos orci 
non, nonummy tristique sit metus, 
velit odio at odio ridiculus. 


Ut dui| libero id ante quis eget, 


varius scelerisque mauris erat a. 
Sit morbi et purus class 
fringilla tortor suspendisse 


ipsum posuere rhoncus ullamcorper 


Text widgets. 


Linux 


Lorem IPSUM dolor sit 


@met, donec a dignissimos orci 
non, nonummy tristique sit metus, 
velit odio at odio ridiculus. 


Utduilibero idante 


varius scelerisque mauris erat a. 
Sit morbi et purus class 


quis eget, 


ip 
fringilla tortorag suspendisse 


ipsum posuere rhoncus ullamcorper 
malesuada. arcu odio lorem lacus. 


While we briefly introduced text widgets in an earlier chapter, we'll go 
into much more detail here. You'll get a better sense of the level of 


sophistication they allow. Still, for any significant work with the text 
widget, the reference manual is well-organized, useful, and a highly- 
recommended read. 

Text widgets are created using the Text class: 


text = Text (parent, width=40, height=10) 


You'll often provide a width (in characters) and height (in lines). As 
always, you can ask the geometry manager to expand it to fill the 
available space in the window. 


15.1. The Basics 


If you simply need a multi-line text field for a form, there are only a few 
things to worry about: creating and sizing the widget (check), providing 
an initial value, and retrieving the text after a user has submitted the 
form. 


Providing Initial Content 


Text widgets start with nothing in them, so we'll need to add any initial 
content ourselves. Because text widgets can hold a lot more than plain 
text, a simple mechanism (like the entry widget's textvariable 
configuration option) isn't sufficient. 

Instead, we'll use the widget's insert method: 


text.insert('1.0', 'here is my\ntext to insert') 


The "1.0" here is the position where to insert the text, and can be read 
as "line 1, character 0". This refers to the first character of the first line. 
Historically, especially on Unix, programmers tend to think about line 
numbers as 1-based and character positions as 0-based. 

The text to insert is just a string. Because the widget can hold multi- 
line text, the string we supply can be multi-line as well. To do this, 
simply embed \n (newline) characters in the string at the appropriate 
locations. 


Retrieving the Text 


After users have made any changes and submitted the form (for 
example), your program can retrieve the contents of the widget via the 
get method: 


thetext = text.get('1.0', 'end') 


The two parameters are the start and end position; end has the obvious 
meaning. You can provide different start and end positions if you want 
to obtain only part of the text. You'll see more on positions shortly. 


Customizing Appearance 


We previously saw the width and height configuration options for text 
widgets. Several others control its overall appearance. The most useful 
are: 


foreground: 


color to draw the text in 
background: 


background color of the widget 
padx, pady: 


extra padding along the inside border of the widget 
borderwidth: 


width of the border around widget 
relief: 


border style: flat, raised, sunken, solid, ridge, groove 


Wrapping and Scrolling 


What if some lines of text in the widget are very long, longer than the 
width of the widget? By default, the text wraps around to the next line. 
This behavior can be changed with the wrap configuration option. It 
defaults to char, meaning wrap lines at any character. Other options 
are word to wrap lines only at word breaks (e.g., spaces), and none 
meaning to not wrap lines at all. In the latter case, some text of longer 
lines won't be visible unless we attach a horizontal scrollbar to the 
widget. (Users can also scroll through the text using arrow keys, even if 
scrollbars aren't present). 

Scrollbars, both horizontal and vertical, can be attached to the text 
widget in the same way as with other widgets, e.g., canvas, listbox. 


t = Text (root, width = 40, height = 5, wrap = "none" ) 

ys = ttk.Scrollbar(root, orient = ' vertical' , command = 
t.yview) 

xs = ttk.Scrollbar(root, orient = ' horizontal' , command = 
t.xview) 

t{[' yscrollcommand'] = ys.set 

t{[' xscrollcommand'] = xs.set 

t.insert('end', "Lorem ipsum...\n...\n...") 

t.grid(column = 0, row = 0, sticky = 'nwes') 
xs.grid(column = 0, row = 1, sticky = 'we') 


ys.grid(column = 1, row = 0, sticky = 'ns') 


root.grid columnconfigure(0, weight = 1) 
root.grid_rowconfigure(0, weight = 1) 
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We can also ask the widget to ensure that a certain part of the text is 
visible. For example, let's say we've added more text to the widget than 
will fit onscreen (so it will scroll). However, we want to ensure that the 
top of the text rather than the bottom is visible. We can use the see 
method. 


text.see('1.0"') 


Disabling the Widget 


Some forms will temporarily disable editing in particular widgets unless 
certain conditions are met (e.g., some other options are set to a certain 
value). To prevent users from changing a text widget, set the state 
configuration option to disabled. Re-enable editing by setting this 
option back to normal. 


text['state'] = 'disabled' 


AXE. As text widgets are part of the classic widgets, the usual state and 
instate methods are not available. 


15.2. Modifying the Text in Code 


While users can modify the text in the text widget interactively, your 
program can also make changes. Adding text is done with the insert 
method, which we used above to provide an initial value for the text 
widget. 


Text Positions and Indices 


When we specified a position of 1.0 (first line, first character), this was 
an example of an index. It tells the insert method where to put the new 
text (just before the first line, first character, i.e., at the very start of the 
widget). Indices can be specified in a variety of ways. We used another 
one with the get method: end means just past the end of the text. (Why 
"just past?" Text is inserted right before the given index, so inserting at 
end will add text to the end of the widget). Note that Tk will always add 
a newline at the very end of the text widget. 

Here are a few additional examples of indices and how to interpret 
them: 


3.end: 
The newline at the end of line 3. 
1,0 + 3 chars: 
Three characters past the start of line 1. 
2.end -1 chars: 
The last character before the new line in line 2. 
end -1 chars: 
The newline that Tk always adds at the end of the text. 
end -2 chars: 
The actual last character of the text. 
end -1 lines: 
The start of the last actual line of text. 
2.2 + 2 lines: 
The third character (index 2) of the fourth line of text. 
2.5 linestart: 
The first character of line 2. 
2.5 lineend: 
The position of the newline at the end of line 2. 


2.5 wordstart: 


First char. of the word with the char. at index 2.5. 
2.5 wordend: 


First char. after the word with the char. at index 2.5. 


Some additional things to keep in mind: 
e The term chars can be abbreviated as c, and lines aS 1. 
e Spaces between terms can be omitted, e.g., 1.0+3c. 


e An index past the end of the text (€.g., end + 100c) is interpreted 
aS end. 


e Indices wrap to subsequent lines as needed; €.g., 1.0 + 10 chars 
on a line with only five characters will refer to a position on the 
second line. 


e Line numbers in indices are interpreted as /ogical lines, i.e., each 
line ends only at the "\n." With long lines and wrapping enabled, 
one logical line may represent multiple display lines. If you'd like to 
move up or down a single line on the display, you can specify this 
as, e.g., "1.0 + 2 display lines". 


To determine the canonical position of an index, use the index idx 
method. Pass it any index expression, and it returns the corresponding 
index in the form iine. char. For example, to find the position of the last 
character (ignoring the automatic newline at the end), use: 


text.index('end') 


You can compare two indices using the compare method, which lets you 
check for equality, whether one index is later in the text than the other, 
etc. 


if text.compare(idxl, "==", idx2"): # same position 


Valid operators are ==, !=, <, <=, >, and >=. 


Deleting Text 


While the insert method adds new text anywhere in the widget, the 
delete start ?end? method removes it. We can delete either a single 


character (specified by index) or a range of characters (specified by 
start and end indices). In the latter case, characters from (and 
including) the start index through to just before the end index will be 
deleted (so the character at the end index is not deleted). So if we 
assume for each of these we start off with abcd\nefgh in the text 
widget: 


text.delete(' 
text.delete(' 
text.delete(' 
text.delete(' 


1.2') => "abd\nefgh" 

1.1", '1.2') > "acd\nefgh" 
1.0', '2.0') > "efgh" 
1.2', '2.1') > “abfgh" 


There is alSO a replace method that performs a delete followed by an 
insert at the same location. 


Example: Logging Window 


Here's a short example that illustrates using a text widget as an 80x24 
logging window for an application. Users don't edit the text widget at 
all. Instead, the program writes log messages to it. We'd like to display 
more than 24 lines (so no scrolling). If the log is full, old messages are 
removed from the top before new ones are added at the end. 


= 


from tkinter import * 


—_ 


from tkinter import ttk 


root = Tk() 

log = Text(root, state='disabled', width=80, height=24, 
wrap='none') 

log.grid() 


def writeToLog(msg) : 
numlines = int(log.index('end - 1 line').split('.') [0]) 
log['state'] = 'normal' 
if numlines==24: 
log.delete(1.0, 2.0) 
if log.index('end-1c')!='1.0': 
log.insert('end', '\n") 
log.insert('end', msg) 
log['state'] = 'disabled' 


Q Note that because the program placed the widget in a disabled state, we had 
re-enable it to make any changes, even from our program. 


15.3. Formatting with Tags 


So far, we've used text widgets when all the text is in a single font. Now 
it's time to look at how to add special formatting, such as bold, italic, 
strikethrough, background colors, font sizes, and much more. Tk's text 
widget implements these using a feature called tags. 

Tags are objects associated with the text widget. Each tag is 
referred to via a name chosen by the programmer. Each tag has 
several configuration options. These are things like fonts and colors 
that control formatting. Though tags are objects having state, they don't 
need to be explicitly created. They are automatically created the first 
time the tag name is used. 


Adding Tags to Text 


Tags can be associated with one or more ranges of text in the widget. 
As before, ranges are specified via indices. A single index represents a 
single character, and a pair of indices represent a range from the start 
character to just before the end character. Tags are added to a range of 
text using the tag_ add method. 


Pert steag ada *highligniiaine’, ta.0"~ 6 —@0") 


Tags can also be provided when first inserting text. The insert method 
supports an optional parameter containing a list of one or more tags to 
add to the text being inserted. 


text.insert('end', 'new material to insert', ('highlightline', 
"recent', 'warning')) 


As the text in the widget is modified, whether by a user or your 
program, the tags will adjust automatically. For example, if we tagged 
the text "the quick brown fox" with the tag "nounphrase", and then 
replaced the word "quick" with "speedy," the tag still applies to the 
entire phrase. 


Applying Formatting to Tags 
Formatting is applied to tags via configuration options; these work 
similarly to configuration options for the entire widget. As an example: 


text.tag configure (*highlightline’, background="yellow", 
font='TkFixedFont', relief='raised') 


Tags support the following configuration options: background, bgstipple, 
borderwidth, elide, fgstipple, font, foreground, justify, Ilmarginl, 
Imargin2, offset, overstrike, relief, rmargin, spacingl, spacing2, 
spacing3, tabs, tabstyle, underline, and wrap. Check the reference 
manual for detailed descriptions of these. The tag cget tag option 
method allows us to query the configuration options of a tag. 

Because multiple tags can apply to the same range of text, there is 
the possibility of conflict (e.g., two tags specifying different fonts). A 
priority order is used to resolve these; the most recently created tags 
have the highest priority, but priorities can be rearranged using the 
tag raise tag and tag lower tag methods. 


More Tag Manipulations 


To delete one or more tags altogether, we can use the tag delete tags 
method. This also, of course, removes any references to the tag in the 
text. We can also remove a tag from a range of text using the 
tag _ remove tag start Pend? method. Even if that leaves no ranges of 
text with that tag, the tag object itself still exists. 

The tag ranges tag method will return a list of ranges in the text that 
the tag has been applied to. There are alSo tag nextrange tag start ? 
end? and tag prevrange tag start Pend? methods to search forward or 
backward for the first such range from a given position. 

The tag names ?idx? method, called with no additional parameters, 
will return a list of all tags currently defined in the text widget (including 
those that may not be presently used). If we pass the method an index, 
it will return the list of tags applied to just the character at the index. 

Finally, we can use the first and last characters in the text having a 
given tag as indices, the same way we can use "end" or "2.5". To do 
So, just specify tagname.first Of tagname.last. 


Differences between Tags in Canvas and Text Widgets 


Both canvas and text widgets support "tags" that can be applied to 
several objects, style them, etc. However, canvas and text tags are not 
the same. There are important differences to take note of. 

In canvas widgets, only individual canvas items have configuration 
options that control their appearance. When we refer to a tag in a 
canvas, the meaning of that is identical to "all canvas items presently 
having that tag." The tag itself doesn't exist as a separate object. So in 
the following snippet, the last rectangle added will not be colored red. 


canvas.itemconfigure('important', fill='red') 
canvas.create rectangle(10, 10, 40, 40, tags=('important') ) 


In contrast, with text widgets, it's not the individual characters that 
retain the state information about appearance, but tags, which are 
objects in their own right. So in this snippet, the newly added text will 
be colored red. 


text.insert('end', 'first text', ('important')) 
text.tag_ configure ('important', foreground='red') 
text.insert('end', 'second text', ('important')) 


15.4. Events and Bindings 


One very cool thing we can do is define event bindings on tags. That 
allows us to do things like easily recognize mouse clicks on particular 
ranges of text, and popup up a menu or dialog in response. Different 
tags can have different bindings. This saves the hassle of sorting out 
questions like "what does a click at this location mean?". Bindings on 
tags are implemented using the tag_ bind method: 


text.tag bind('important', '<1>', popupImportantMenu) 


Widget-wide event bindings continue to work as they do for every other 
widget, e.g., to capture a mouse click anywhere in the text. Besides the 
normal low-level events, the text widget generates a <<Modified>> 
virtual event whenever a change is made to the content of the widget, 
and a <<Selection>> virtual event whenever there is a change made to 
which text is selected. 


15.5. Selecting Text 


We can identify the range of text selected by a user, if any. For 
example, an editor may have a toolbar button to bold the selected text. 
While you can tell when the selection has changed (e.g., to update 
whether or not the bold button is active) via the <<selection>> virtual 
event, that doesn't tell you what has been selected. 

The text widget automatically maintains a tag named sei, which 
refers to the selected text. Whenever the selection changes, the sei 
tag will be updated. So we can find the range of text selected using the 
tag ranges ?tag? method, passing it sei as the tag to report on. 

Similarly, we can change the selection by using tag add to set a new 
selection, or tag_ remove to remove the selection. The sei tag cannot be 
deleted, however. 


Q Though the default widget bindings prevent this from happening, sei is 
like any other tag in that it can support multiple ranges, 1.e., disjoint 
selections. To prevent this from happening, when changing the selection 

from your code, make sure to remove any old selection before adding a new one. 


The text widget manages the concept of the insertion cursor (where 
newly typed text will appear) separate from the selection. It does so 
using a new concept called a mark. 


15.6. Marks 


Marks indicate a particular place in the text. In that respect, they are 
like indices. However, as the text is modified, the mark will adjust to be 
in the same relative location. In that way, they resemble tags, but refer 
to a single position rather than a range of text. Marks actually don't 
refer to a position occupied by a character in the text but specify a 
position between two characters. 

Tk automatically maintains two different marks. The first, named 
insert, is the present location of the insertion cursor. As the cursor is 
moved (via mouse or keyboard), the mark moves with it. The second 
mark, named current, tracks the position of the character underneath 
the current mouse position. 

To create your own marks, use the widget's mark set name idx 
method, passing it the name of the mark and an index (the mark is 
positioned just before the character at the given index). This is also 
used to move an existing mark to a different position. Marks can be 
removed using the mark unset name method, passing it the name of the 
mark. If you delete a range of text containing a mark, that also removes 
the mark. 

The name of a mark can also be used as an index (in the same way 
1.0 Of end-ic are indices). You can find the next mark (or previous one) 
from a given index in the text using the mark next idx Of mark previous 
idx methods. The mark names method will return a list of the names of 
all marks. 

Marks also have a gravity, which can be modified with the 
mark gravity name ?direction? method, which affects what happens 
when text is inserted at the mark. Suppose we have the text "ac" with a 
mark in between that we'll symbolize with a pipe, i.e., "alc." If the 
gravity of that mark is right (the default), the mark attaches itself to the 
"c." If the new text "b" is inserted at the mark, the mark will remain 
stuck to the "c," and so the new text will be inserted before the mark, 
i.e., "ablc." If the gravity is instead ieft, the mark attaches itself to the 
"a," and so new text will be inserted after the mark, i.e., "ajbc." 


15.7. Images and Widgets 


Like canvas widgets, text widgets can contain not only text but also 
images and any other Tk widgets (including a frame, itself containing 
many other widgets). In a sense, this allows the text widget to work as 
a geometry manager in its own right. The ability to add images and 
widgets within the text opens up a world of possibilities for your 
program. 

Images are added to a text widget at a particular index, with the 
image specified as an existing Tk image. Other options that allow you 
to fine-tune padding, etc. 


flowers = PhotoImage(file='flowers.gif') 
text.image create('sel.first', image=flowers) 


Other widgets are added to a text widget in much the same way as 
images. The widget being added must be a descendant of the text 
widget in the widget hierarchy. 


b = ttk.Button(text, text='Push Me') 
text.window create('1.0', window=b) 


15.8. Even More 


Text widgets can do many more things. Here, we'll briefly mention just 
a few more of them. For details on any of these, see the reference 
manual. 


Search 


The text widget includes a powerful search method that allows you to 
locate a piece of text within the widget. This is useful for a "Find" 
dialog, as one obvious example. You can search backward or forward 
from a particular position or within a given range, specify the search 
term using exact text, case insensitive, or via regular expressions, find 
one or all occurrences of the search term, etc. 


Modifications, Undo and Redo 


The text widget keeps track of whether changes have been made to 
the text (useful to know whether it needs to be saved to a file, for 
example). We can query (or change) using the edit modified ?bool? 
method. There is also a complete multi-level undo/redo mechanism, 
managed automatically by the widget when we set its undo 
configuration option to true. Calling edit undo or edit redo modifies 
the current text using information stored on the undo/redo stack. 


Eliding Text 


Text widgets can include text that is not displayed. This is known as 
"elided" text, and is made available using the e1ide configuration option 
for tags. It can be used to implement an outliner, a "folding" code editor, 
or even to bury extra meta-data intermixed with displayed text. When 
specifying positions within elided text, you have to be a bit more 
careful. Methods that work with positions have extra options to either 
include or ignore the elided text. 


Introspection 


Like most Tk widgets, the text widget goes out of its way to expose 
information about its internal state. We've seen this in terms of the get 
method, widget configuration options, names and cget for both tags and 
marks, etc. There is even more information available that can be useful 
for a wide variety of tasks. Check out the debug, dlineinfo, bbox, count, 
and dump methods in the reference manual. 


Peering 


The Tk text widget allows the same underlying text data structure 
(containing all the text, marks, tags, images, etc.) to be shared 
between two or more different text widgets. This is known as peering 
and is controlled via the peer method. 


16. Treeview 


vel ttk.Treeview 


[3 https://tkdocs.com/man/ttk_treeview 


A treeview widget displays a hierarchy of items and allows users to 
browse through it. One or more attributes of each item can be 
displayed as columns to the right of the tree. It can be used to build 
user interfaces similar to the tree display you'd find in file managers 
like the macOS Finder or Windows Explorer. As with most Tk 
widgets, it offers incredible flexibility so it can be customized to suit a 
wide range of situations. 


macOS 
Size Modified 
widgets 25KB Yesterday 
gallery 2KB Two weeks ago 
» resources 220KB Three weeks ago 
¥ tutorial 2.1MB Ten minutes ago 
canvas 18KB Last week 
tree SKB Ten minutes ago 
text 12KB Yesterday 


Windows 
Size Modified 

widgets 25KB Yesterday 
getlery 2KB Two weeks ego 
resources 220KB Three weeks ago 
tutonal 21MB Ten minutes ago 

tree SKB Ten minutes ago 

text 2KB Yesterday 


Treeview widgets. 


Linux 


25K8 Yesterday 
gallery 2KB Two weeks ago 
220KB Three weeks ago 
2.1MB Ten minutes ago 
18KB Last week 

SKB Ten minutes ago 
text 12KB Yesterday 


carivas 


Treeview widgets are created using the ttk.tTreeview Class: 


tree = ttk.Treeview (parent) 


Horizontal and vertical scrollbars can be added in the usual manner 
if desired. 


16.1. Adding Items to the Tree 


To do anything useful with the treeview, we'll need to add one or 
more items to it. Each item represents a single node in the tree, 
whether a leaf node or an internal node containing other nodes. 
Items are referred to by a unique id. You can assign this id when the 
item is first created, or the widget can automatically generate one. 

Items are created by inserting them into the tree, using the 
treeview's insert method. To insert an item, we need to know where 
to insert it. That means specifying the parent item and where within 
the list of the parent's existing children the new item should be 
inserted. 

The treeview widget automatically creates a root node (which is 
not displayed). Its id is the empty string. It serves as the parent of the 
first level of items that are added. Positions within the list of a node's 
children are specified by index (0 being the first, and ena meaning 
insert after all existing children). 

Normally, you'll also specify the name of each item, which is the 
text displayed in the tree. Other options allow you to add an image 
beside the name, specify whether the node is open or closed, etc. 


# Inserted at the root, program chooses id: 
tree.insert('', 'end', 'widgets', text='Widget Tour') 


# Same thing, but inserted as first child: 
tree.insert('', 0, 'gallery', text='Applications'") 


# Treeview chooses the id: 
id = tree.insert('', 'end', text='Tutorial') 


# Inserted underneath an existing node: 
tree.insert('widgets', 'end', text='Canvas') 
tree.insert(id, 'end', text='Tree') 


Inserting the item returns the id of the newly created item. 


16.2. Rearranging Items 


A node (and its descendants, if any) can be moved to a different 
location in the tree. The only restriction is that a node cannot be 
moved underneath one of its descendants, for obvious reasons. As 
before, the target location is specified via an existing parent node, 
and a position within its list of children. 


tree.move('widgets', 'gallery', 'end') # move widgets under 
gallery 


Items can be detached from the tree, which removes the item and its 
descendants from the hierarchy, but does not destroy the items. This 
allows us to later reinsert them with move. 


tree.detach('widgets') 


Items can also be deleted, which does completely destroy the item 
and its descendants. 


tree.delete('widgets') 


To traverse the hierarchy, there are methods to find the parent of an 
item (parent item), its next or previous sibling (next item and prev 
item), and return the list of children of an item (children item). 

We can control whether or not the item is open and shows its 
children by modifying the open item configuration option. 


tree.item('widgets', open=TRUE) 
isopen = tree.item('widgets', 'open') 


16.3. Displaying Information for each Item 


The treeview can display one or more additional pieces of 
information about each item. These are shown as columns to the 
right of the main tree display. 

Each column is referenced by a symbolic name that we assign. 
We can specify the list of columns using the columns configuration 
option of the treeview widget, either when first creating the widget, or 
later on. 


tree = ttk.Treeview(root, columns=('size', 'modified') ) 
tree['columns'] = ('size', 'modified', 'owner') 


We can specify the width of the column, how the display of item 
information in the column is aligned, and more. We can also provide 
information about the heading of the column, such as the text to 
display, an optional image, alignment, and a script to invoke when 
the item is clicked (e.g. to sort the tree). 


tree.column('size', width=100, anchor='center') 
tree.heading('size', text='Size') 


What to display in each column for each item can be specified 
individually by using the set method. You can also provide a list 
describing what to display in all the columns for the item. This is 
done using the values item configuration option. It can be used either 
when first inserting the item or to update it later). It takes a list of 
values. The order of the list must be the same as the order in the 
columns widget configuration option. 


tree.set('widgets', 'size', '12KB') 
size = tree.set('widgets', 'size') 
tree.insert('', ‘'end', text='Listbox', values=('15KB', 


"'Yesterday', 'mark')) 


16.4. Item Appearance and Events 


Like the text and canvas widgets, the treeview widget uses fags to 
modify the appearance of items in the tree. We can assign a list of 
tags to each item using the tags item configuration option (again, 
when creating the item or later on). 

Configuration options can then be specified on the tag, which will 
then apply to all items having that tag. Valid tag options include 
foreground (text color), background, font, and image (not used if the 
item specifies its own image). 

We can also create event bindings on tags, which lets us capture 
mouse clicks, keyboard events etc. 


tree.insert('', 'end', text='button', tags=('ttk', 'simple')) 
Eree.tag configure ('ttk', background=" yellow") 
Creestag bind(*tck*, "<1>"; itemClicked) 


# the item clicked can be found via tree. focus () 


The treeview will generate virtual events <<TreeviewSelect>>, 
<<TreeviewOpen>>, and <<TreeviewClose>>, which allow us to monitor 
changes to the widget made by users. We can use the selection 
method to determine the current selection (the selection can also be 
changed from your program). 


16.5. Customizing the Display 


There are many aspects of how the treeview widget is displayed that 
we can customize. We've already seen some of them, such as the 
text of items, fonts and colors, names of column headings, and 
more. Here are a few additional ones. 


Specify the desired number of rows to show using the height 
widget configuration option. 


Control the width of each column using the column's width or 
minwidth options. The column holding the tree can be accessed 
with the symbolic name #0. The overall requested width for the 
widget is based on the sum of the column widths. 


Choose which columns to display and the order to display them 
in using the displaycolumns widget configuration option. 


You can optionally hide one or both of the column headings or 
the tree itself (leaving just the columns) using the show widget 
configuration option (default is "tree headings" to show both). 


You can specify whether a single item or multiple items can be 
selected by users via the selectmode widget configuration 
option, passing browse (single item), extended (multiple items, 
the default), OF none. 


17. Styles and Themes 


The themed aspect of the modern Tk widgets is one of the most 
powerful and exciting aspects of the newer widget set. Yet, it's also one 
of the most confusing. 

This chapter explains styles (which control how widgets like buttons 
look) and themes (which are a collection of styles that define how all the 
widgets in your application look). Changing themes can give your 
application an entirely different look. 
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Note that it's not just colors that have changed, but the actual shape of 
individual widgets. Styles and themes are extremely flexible. 


Why? 


However, before you get carried away, very few applications will benefit 
from switching themes like this. Some games or educational programs 
might be exceptions. Using the standard Tk theme for a given platform 
will display widgets the way that people expect to see them, particularly 
if they're running macOS and Windows. 


AXE. On Linux systems, there's far less standardization of look and feel. Users 
expect (and are more comfortable with) some variability and "coolness." 
Because different widget sets (typically GTK and QT) are used by window 

managers, control panels, and other system utilities, Tk can't seamlessly blend in 
with the current settings on any particular system. Most of the Linux screenshots in 
this book use Tk’'s ait theme. Despite users being accustomed to variability, there 
are limits to what most users will accept. The styling of core widgets in Tk's classic 
widget set, matching circa-1992 OSF/Motif, is a prime example. 


Styles and themes, used in a more targeted manner and with significant 
restraint, can have a role to play in modern applications. This chapter 
explains why and when you might want to use them and how to go 
about doing so. We'll begin by drawing a parallel between Tk's styles 
and themes and another realm of software development. 


Understanding Styles and Themes 


If you're familiar with web development, you know about cascading 
stylesheets (CSS). There are two ways it can be used to customize the 
appearance of an element in your HTML page. In the first way, you add 
a bunch of style attributes (fonts, colors, borders, etc.) directly to an 
element in your HTML code via the style attribute. For example: 


<label style="color:red; font-size:14pt; font-weight:bold; 
background-color:yellow; ">Meltdown imminent!</label> 


The other way to use CSS is to attach a class to each widget via the 
class attribute. The details of how elements of that class appear are 
provided elsewhere, often in a separate CSS file. You can attach the 
same class to many elements, and they will all have the same 
appearance. You don't need to repeat the full details for every element. 
More importantly, you separate the logical content of your site (HTML) 
from its appearance (CSS). 


<label class="danger">Meltdown imminent!</label> 


<style type="text/css"> 
label.danger {color:red; font-size:14pt; font-weight:bold; 
background-color: yellow; } 

</style> 


Back to Tk. 


e In the classic Tk widgets, all appearance customizations require 
specifying each detail on individual widgets, akin to always using 
the style HTML attribute. 


e In the themed Tk widgets, a// appearance customizations are made 
via attaching a style to a widget, akin to using the class HTML 
attribute. Separately, you define how widgets with that style will 
appear, akin to writing CSS. 


e Unlike with HTML, you cant freely mix and match. You can't 
customize some themed entries or buttons with styles, and others 
by directly changing appearance options. 


AXE. Yes, there are a few exceptions, like labels where you can customize the 
font and colors through both styles and configuration options. 


Benefits 


So why use styles and themes in Tk? They take the fine-grained details 
of appearance decisions away from individual instances of widgets. 

That makes for cleaner code and less repetition. If you have 20 entry 
widgets in your application, you don't need to repeat the same 
appearance details every time you create one (or write a wrapper 
function). You just assign them a style. 

Styles also put all appearance decisions in one place. And because 
styles for a button and styles for a widget can share common elements, 
it promotes consistency and improves reuse. 


fii. Styles also have many benefits for widget authors. Widgets can delegate 
most appearance decisions to styles. A widget author no longer has to 
hardcode logic to the effect of "when the state is disabled, consult the 
‘disabledforeground' configuration option and use that for the foreground color." Not 
only did that make coding widgets longer (and more repetitive), but it also restricted 


how a widget could be changed based on its state. If the widget author hadn't 
coded in logic to change the font when the state changed, you as an application 
developer using the widget were out of luck. 


Using styles, widget authors don't need to provide code for every possible 
appearance option. That not only simplifies the widget but paradoxically ensures 
that a wider range of appearances can be set, including those the widget author 
may not have anticipated. 


17.1. Using Existing Themes 


Before delving into the weightier matters of tastefully and selectively 
modifying and applying styles to improve the usability of your application 
and cleanliness of your code, let's deal with the fun bits: using existing 
themes to completely reskin your application. 

Themes are identified by a name. You can obtain the names of all 


available themes: 


>>> s = ttk.Style() 


>>> s.theme_names () 
('aqua', 'step', 'clam', ‘alt', 'default', 'classic') 


AXE. Tkinter encapsulates all style manipulations in the :tk.style class. We'll 
therefore need an instance of that class for this and other operations. 
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Built-in themes. 


Besides the built-in themes (ait, default, clam, and classic), macOS 

includes a theme named aqua to match the system-wide style, while 

Windows includes themes named vista, winxpnative, and winnative. 
Only one theme can ever be active at a time. To obtain the name of 


the theme currently in use, use the following: 


>>> s.theme_use() 
"aqua' 


AXE. This API, which was originally targeted for Tk 8.6, was back-ported to Tk 
8.5.9. If you're using an earlier version of Tk getting this info is a bit trickier. 


Switching to a new theme can be done with: 


s.theme use ('themename' ) 


What does this actually do? Obviously, it sets the current theme to the 
indicated theme. Doing this, therefore, replaces all the currently 
available styles with the set of styles defined by the theme. Finally, it 
refreshes all widgets, so that they take on the appearance described by 
the new theme. 


Third-Party Themes 


With a bit of looking around, you can find some existing add-on themes 
available for download. A good starting point is https://wiki.tcl- 
lang.org/page/List+ of+ttk+ Themes. 

Though themes can be defined in any language that Tk supports, 
most that you will find are written in Tcl. How can you install them so that 
they are available to use in your application? 

As an example, let's use the "awdark" theme, available from 
awthemes-*.zip file somewhere. You'll notice it contains a bunch of .tc1i 
files, a subdirectory i containing more directory with images used by the 
theme, etc. 

One of the files is named pkgindex.tcl. This identifies it as a Tcl 
package, which is similar to a Python module. If we look inside, you'll 
see a bunch of lines like package ifneeded awdark 7.7. Here, awdark Is 
the name of the package, and 7.7 is its version number. It's not unusual, 
as in this case, for a single pkgIndex.tci file to provide several 
packages. 

To use it, we need to tell Tcl where to find the package (via adding its 
directory to Tcl's auto path) and the name of the package to use. 


root.tk.call('lappend', ‘auto path', '/full/path/to/awthemes- 
9.3.1") 
root.tk.call('package', 'require', 'awdark") 


If the theme is instead implemented as a single Tcl source file, without a 
pkgIndex.tcl, you can make it available like this: 


root.tk.call('source', '/full/path/to/themefile.tcl') 


You should now be able to use the theme in your own application, just 
as you would any of the built-in themes. 


17.2. Using Styles 


We'll now tackle the more difficult issue of how to take full advantage of 
styles and themes within your application, not just reskinning it with an 
existing theme. 


Definitions 
We first need to introduce a few essential concepts. 


Widget Class 
A widget class identifies the type of a particular widget, whether it is a 


button, a label, a canvas, etc. All themed widgets have a default class. 
Buttons have the class TButton, labels TLabel, etc. 


Widget State 


A widget state allows a single widget to have more than one appearance 
or behavior, depending on things like mouse position, different state 
options set by the application, and so on. 

As you'll recall, all themed widgets maintain a set of binary state flags, 
accessed by the state and instate methods. The flags are: active, 
disabled, focus, pressed, selected, background, readonly, alternate, and 
invalia. All widgets have the same set of state flags, though they may 
ignore some of them (e.g., a label widget would likely ignore an invalid 
state flag). See the themed widget page in the reference manual for the 
exact meaning of each state flag. 


[3 https://tkdocs.com/man/ttk_widget 


Style 


A style describes the appearance (or appearances) of a widget class. All 
themed widgets having the same widget class will have the same 
appearance(s). 


Styles are referred to by the name of the widget class they describe. 
For example, the style rautton defines the appearance of all widgets 
with the class TButton. 

Styles know about different states, and one style can define different 
appearances based on a widget's state. For example, a style can 
specify how a widget's appearance should change if the pressea state 
flag is set. 


Theme 


A theme is a collection of styles. While each style is widget-specific (one 
for buttons, one for entries, etc.), a theme collects many styles together. 
All styles in the same theme will be designed to visually "fit" together 
with each other. (Tk doesn't technically restrict bad design or judgment, 
unfortunately!) 

Using a particular theme in an application really means that, by 
default, the appearance of each widget will be controlled by the style 
within that theme responsible for that widget class. 


Style Names 


Every style has a name. If you're going to modify a style, create a new 
one, or use a style for a widget, you need to know its name. 

How do you know what the names of the styles are? If you have a 
particular widget, and you want to know what style it is currently using, 
you can first check the value of its style configuration option. If that is 
empty, it means the widget is using the default style for the widget. You 
can retrieve that via the widget's class. For example: 


>>> b = ttk.Button () 
>>> b[' style’ ] 


>>> b.winfo_ class () 
'TButton' 


In this case, the style that is being used is TButton. The default styles for 
other themed widgets are named similarly, €.g., TEntry, TLabel, etc. 


Qa It's always wise to check the specifics. For example, the treeview widget's 
class is Treeview, NOt TTreeview. 


Beyond the default styles, though, styles can be named pretty much 
anything. You might create your own style (or use a theme that has a 
style) named FunButton, NuclearReactorButton, Of @VEN GuessWhatIAm 
(not a smart choice). 

More’ often, you'll find names’ like = Fun.tTButton or 
NuclearReactor.TButton, which suggest variations of a base style; as 
you'll see, this is something Tk supports for creating and modifying 
styles. 


@ The ability to retrieve a list of all currently available styles is currently not 

supported. This will likely appear in Tk 8.7 in the form of a new command, 

ttk::style theme styles to return the list of styles implemented by a 

theme. It also proposes adding a styie method for all widgets, so you don't have to 

examine both the widget's style configuration option and its class. See TIP #584 
(https:/Aip.tcl.tk8 4). 


Applying a Style 


To use a style means to apply that style to an individual widget. If you 
know the name of the style you want to use, and which widget to apply it 
to, it's easy. Setting the style can be done at creation time: 


b = ttk.Button(parent, text='Hello', style='Fun.TButton') 


As well, a widget's style can be changed at any time with the style 
configuration option: 


b['style'] = 'Emergency.TButton' 


Creating a Simple Style 


So how do we create a new style like Emergency. TButton? 

In situations like this, you're creating a new style similar to an existing 
one but varies in a certain aspect. This is the most common reason for 
creating new styles. 

For example, you want most of the buttons in your application to keep 
their normal appearance, but have certain "emergency" buttons 
highlighted differently. Creating a new style (e€.g., Emergency.TButton), 
derived from the base style (TButton), is the appropriate thing to do. 


Prepending another name (Emergency) followed by a dot onto an 
existing style creates a new style derived from the existing one. The new 
style will have exactly the same options as the existing one except for 
the indicated differences: 


s.configure('Emergency.TButton', font='helvetica 24', 
foreground='red', padding=10) 


You could then apply that style to an individual button widget using its 
style configuration option, as shown earlier. Every other button widget 
would retain its normal appearance. 

How do you know what options are available to change for a given 
style? That requires diving a little deeper inside styles. 


You may have existing code using the classic widgets that you'd like to 
move to the themed widgets. Most appearance changes made to classic 
widgets through configuration options can probably be dropped. For those 
that can't, you may need to create a new style, as shown above. 


UPGRADE 
ENE 


State-specific appearance changes can be treated similarly. In classic Tk, several 
widgets supported a few state changes via configuration options. For example, 
setting a button's state option to disabled would draw it with a greyed-out label. 
Some allowed an additional state, active, which represented a different 
appearance. You could control the appearance of the widget in different states via 
additional configuration options, @.g., foreground, disabledforeground, and 


activeforeground. 


State changes via configuration options should be changed to use the state 
method on themed widgets. Configuration options to modify the appearance of a 
widget when in a particular state should be dealt with in the style. 


Classic Tk widgets also supported a very primitive form of styles that you may 
encounter. This used the option database, a now-obscure front end to X11-style 
configuration files. 


In classic Tk, all buttons had the same class (Button), all labels had the same class 
(Label), etc. You could use this widget class both for introspection and for changing 
options globally through the option database. It let you say, for example, that all 
buttons should have a red background. 


A few classic Tk widgets, including frame and toplevel widgets, let you change the 
widget class of a particular widget when it was first created by providing a class 
configuration option. For example, you could specify that one particular frame 
widget had a class of specialFrame, While others would have the default class 


Frame. You could use the option database to change the appearance of just the 
SpecialFrame frames. 


Styles and themes take that simple idea and give it rocket boosters. 


17.3. What's Inside a Style? 


If all you want to do is use a style or create a new one with a few 
tweaks, you now know everything you need. If, however, you want to 
make more substantial changes, things start to get "interesting." 


Elements 


While each style controls a single type of widget, each widget is usually 
composed of smaller pieces, called elements. It's the job of the style 
author to construct the entire widget out of these smaller elements. What 
these elements are depends on the widget. 

Here's an example of a button. It might have a border on the very 
outside. That's one element. Just inside that, there may be a focus ring. 
Normally, it's just the background color, but could be highlighted when a 
user tabs into the button. So that's a second element. Then there might 
be some spacing between that focus ring and the button's label. That 
spacing is a third element. Finally, the text label of the button itself is a 
fourth element. 


Focus ring element 


Spacing element 


Label 


Label element 


Border element 


Possible elements of a button. 


Why might the style author have divided it up that way? If you have one 
part of the widget that may be in a different location from another or 
might be a different color than another, it may be a good candidate for 
an element. Note that this is just one example of how a button could be 


constructed from elements. Different styles and themes could (and do) 
accomplish this in different ways. 

Here is a second example, for a vertical scrollbar. It consists of a 
"trough" element, which contains other elements. These include the up 
and down arrow elements at either end and a "thumb" element in the 
middle (it might have other elements too, like borders). 


Arrow element 


Thumb element Trough element 


Arrow element 


Possible elements of a scrollbar. 


Layout 


Besides specifying which elements make up a widget, a style also 
defines how those elements are arranged within the widget. This is 
called their layout. In the button example, we had a label element inside 
a spacing element, inside a focus ring element, inside a border element. 
Its logical layout is this: 


border { 
focus { 
spacing { 
label 


} 


We can ask Tk for the layout of the TButton style: 


>>> s.layout(' TButton!' ) 


[("Button.border", {"children": [("Button.focus", {"children": 
[("Button.spacing", 

{"children": [("Button.label", {"sticky": "nswe"})], "sticky": 
"nswe"})], 

"Sticky": "nswe"})], "sticky": "nswe", "border": "1"})] 


If we clean this up and format it a bit, we get something with this 
structure: 


Button.border -sticky nswe -border 1 -children { 
Button.focus -sticky nswe -children { 
Button.spacing -sticky nswe -children { 
Button.label -sticky nswe 


} 


This starts to make sense; we have four elements, named 
Button.border, Button.focus, Button.spacing, and Button. label. Each of 
these has different element options, such aS children, sticky, and 
border that specify layout or sizes. Without getting into too much detail 
at this point, we can clearly see the nested layout, based on the 
children and sticky attributes. 


XL. Styles uses a simplified version of Tk's pack geometry manager to specify 
lement layout. This is detailed in the style reference manual page. 
J = https:/Akdocs.com/man/tk_style 


Element Options 


Each of these elements has a number of different options. For example, 
a label element has a font and a foreground color. An element 
representing the thumb of a scrollbar may have an option to set its 
background color or another to provide the width of a border. These can 
be customized to adjust how the elements within the overall widget look. 

You can determine what options are available for each element? 
Here's an example of checking what options are available for the label 


inside the button (which we know from the layout method is identified as 
Button.label): 


>>> s.element_options (' Button.label' ) 

('compound', 'space', 'text', 'font', 'foreground', '‘underline', 
"width', ‘anchor', 'justify', 

'wraplength', 'embossed', ‘image', 'stipple', 'background') 


In the next sections, we'll look at the not-entirely-straightforward way to 
work with element options. 


17.4. Manipulating Styles 


In this section, we'll see how to change the style's appearance by 
modifying style options. You can do this either by modifying an existing 
style, or more typically, by creating a new style. We saw how to create a 
simple style that was derived from another one earlier: 


s.configure('Emergency.TButton', font='helvetica 24', 
foreground='red', padding=10) 


Modifying a Style Option 

Modifying an option for an existing style is done in a similar fashion as 
modifying any other configuration option, by specifying the style, name 
of the option, and new value: 


s.configure('TButton', font='helvetica 24') 


You'll learn more about what the valid options are shortly. 


Q If you modify an existing style, like we've done here with tButton, that 
modification will apply to all widgets using that style (so by default, all 
buttons). That may well be what you want to do. 


To retrieve the current value of an option, use the lookup method: 


>>> s.lookup(' TButton!' , ' font' ) 
"helvetica 24' 


State Specific Style Options 


Besides the normal configuration options for the style, the widget author 
may have specified different options to use when the widget is in a 
particular widget state. For example, when a button is disabled, it may 
change the button's label to grey. 


Remember that the state is composed of one or more state flags (or their 
negation), as set by the widget's state method, or queried via the instate 


method. 


You can specify state-specific variations for one or more of a style's 
configuration options with a map. For each configuration option, you can 
specify a list of widget states, along with the value that option should be 
assigned when the widget is in that state. 

The following example provides for the following variations from a 
button's normal appearance: 


e when the widget is in the disabled state, the background color 
should be set to #a9a9a9 


e when the widget is in the active state (mouse over it), the 
background color should be set to #ececec 


e when the widget is in the disabled state, the foreground color should 
be set to #a3a3a3 (this is in addition to the background color change 
we already noted) 


¢ when the widget is in the state where the button is pressed, and the 
widget is not disabled, the relief should be set to sunken 


s.map('TButton', 


background=[ ('disabled','#d9d9d9'), ('active','#ececec')], 
foreground=[('disabled','#a3a3a3')], 
relief=[('pressed', '!disabled', 'sunken') ]) 


fii. Because widget states can contain multiple flags, more than one state may 
match an option (e.9., pressed and pressed !disabled Will both match if the 
widget's pressed State flag is set). The list of states is evaluated in the order 

you provide in the map command. The first state in the list that matches is used. 


17.5. Sound Difficult to you? 


So you now know that styles are made up of elements, which have a 
variety of options, and are composed together in a particular layout. You 
can change various options on styles to make all widgets using the style 
appear differently. Any widgets using that style take on the appearance 
that the style defines. Themes collect an entire set of related styles, 
making it easy to change the appearance of your entire user interface. 

So what makes styles and themes so difficult in practice? Three 
things. First: 


You can only modify options for a style, not element options (except 
sometimes). 


We talked earlier about how to discover what elements were used in the 
style by examining the style's layout, and also how to discover what 
options were available for each element. But when we went to make 
changes to a style, we seemed to be configuring an option for the style, 
without specifying an individual element. What's going on? 

Again, using our button example, we had an element Button. label, 
which, among other things, had a font configuration option. What 
happens is that when that Button. 1abe1 element is drawn, it looks at the 
font Configuration option set on the style to determine what font to draw 
itself in. 


AXE. To understand why, you need to know that when a style includes an 
element as a piece of it, that element does not maintain any (element- 
specific) storage. In particular, it does not store any configuration options 

itself. When it needs to retrieve options, it does so via the containing style, which is 
passed to the element. Individual elements, therefore, are “flyweight" objects in 
GoF pattern parlance. 


Similarly, any other elements will lookup their configuration options from 
options set on the style. What if two elements use the same 
configuration option (like a background color)? Because there is only 
one background configuration option, stored in the style, both elements 
will use the same background color. You can't have one element use 
one background color, and the other use a different background color. 


& Except when you can. There are a few nasty, widget-specific things called 
sublayouts in the current implementation, which let you sometimes modify 
just a single element, via configuring an option like tButton.Label (rather 

than just TButton, the name of the style). 


Some styles also provide additional configuration options that let you specify what 
element the option effects. For example, the tcheckbutton Style provides a 
background option for the main part of the widget and an indicatorbackground 
option for the box that shows whether it is checked. 


Are the cases where you can do this documented? Is there some way to introspect 
to determine when you can do this? Sometimes to both (believe it or not, this is an 
improvement; the answer to both used to be a clear "no"). You can sometimes find 
some of the style's options by calling the style’s configure method without 
providing any new configuration options. The reference manual pages for each 
themed widget now generally include a styling options section that lists options 
that may be available to change. 


This is one area of the themed widget API that continues to evolve over time. 
The second difficulty is also related to modifying style options: 


Options that are available don't necessarily have an effect, and it's 
not an error to modify a bogus option. 


You'll sometimes try to change an option that is supposed to exist 
according to element options, but it will have no effect. For example, you 
can't modify the background color of a button in the aqua theme used by 
macOS. While there are valid reasons for these cases, it's not easy to 
discover them, which can make experimenting frustrating at times. 
Perhaps more frustrating when you're experimenting is that specifying 
an incorrect Style name or option name does not generate an error. 
When doing a configure OF lookup you can, in fact, specify any name at 
all for a style, and specify any name at all for an option. So if you're 
bored with the background and font options, feel free to configure a 
dowhatimean option. It may not do anything, but it's not an error. Again, it 
may make it hard to know what you should be modifying and what you 
shouldn't. 


AX. This is one of the downsides of having a very lightweight and dynamic 
system. You can create new styles by just providing their name when 
configuring style options; this means you don't need to explicitly create a 


style object. At the same time, this does open itself to errors. It's also not possible 
to find out what styles currently exist or are used. And because style options are 
really just a front end for element options, and the elements in a style can change 
at any time, it's not necessarily obvious that options should be restricted to those 
referred to by current elements alone, which may themselves not all be 
introspectable. 


Finally, here is the last thing that makes styles and themes so difficult: 


The elements available, the names of those elements, which 
options are available or have an effect for each of those elements, 
and which are used for a particular widget can be different in every 
theme. 


So? Remember, the default theme for each platform (Windows, macOS, 
and Linux) is different (which is a good thing). Some implications of this: 


1. If you want to define a new type of widget (or a variation of an 
existing widget) for your application, you'll need to do it separately 
and differently for each theme your application uses (i.e., at least 
three for a cross-platform application). 


2. The elements and options available will differ for each 
theme/platform, meaning you may have to come up with a quite 
different customization approach for each theme/platform. 


3. The elements, names, and element options available with each 
theme are not typically documented (outside of reading the theme 
definition files themselves), but are generally identified via theme 
introspection (which we'll see soon). Because all themes aren't 
available on all platforms (€.g., aqua is only available on macOS), 
you'll need ready access to every platform and theme you need to 
run on. 


Consider trying to customize a button. You know it uses the rTButton 
style. But that style is implemented using a different theme on each 
platform. If you examine the layout of that style in each theme, you'll 
discover each uses different elements, arranged differently. If you try to 
find the advertised options available for each element, you see those are 
different too. And of course, even if an option is nominally available, it 
may not have an effect). 


The bottom line is that in classic Tk, where you had the ability to 
modify any of a large set of attributes for an individual widget, you'd be 
able to do something on one platform and it would sorta-kinda work (but 
probably need tweaking) on others. In themed Tk, the easy option just 
isn't there, and you're pretty much forced to do it the right way if you 
want your application to work with multiple themes/platforms. It's more 
work upfront. 


17.6. Advanced: More on Elements 


While that's about as far as we're going to go on styles and themes in 
this book, for curious users and those who want to delve further into 
creating new themes, we can provide a few more interesting tidbits 
about elements. 

Because elements are the building blocks of styles and themes, it 
begs the question of "where do elements come from?" Practically 
speaking, we can say that elements are normally created in C code and 
conform to a particular API that the theming engine understands. 

At the very lowest level, elements come from something called an 
element factory. At present, there is a default one, which most themes 
use, and uses Tk drawing routines to create elements. A second allows 
you to create elements from images and is actually accessible at the 
script level using the ttk::style element create method (from Tcl). Any 
image format supported by Tk is available, including scalable image 
formats like SVG, if you have the right extension. Finally, there is a third, 
Windows-specific engine using the underlying "Visual Styles" platform 
API. 

If a theme uses elements created via a platform's native widgets, the 
calls to use those native widgets will normally appear within that theme's 
element specification code. Of course, themes whose elements depend 
on native widgets or API calls can only run on the platforms that support 
them. 

Themes will then take a set of elements and use those to assemble 
the styles that are actually used by the widgets. And given the whole 
idea of themes is that several styles can share the same appearance, 
it's not surprising that different styles share the same elements. 

So while the TButton style includes a Button. padding element, and the 
TEntry Style includes an Entry.padding element, underneath, these 
padding elements are more than likely one and the same. They may 
appear differently, but that's because of different configuration options, 
which as we recall, are stored in the style that uses the element. 

It's also probably not surprising to find out that a theme can provide a 
set of common options that are used as defaults for each style if the 
style doesn't specify them otherwise. This means that if pretty much 
everything in an entire theme has a green background, the theme 


doesn't need to explicitly say this for each style. This uses a root style 
named .. After all, if Fun.tButton can inherit from tTButton, why can't 
TButton inherit from .? 

Finally, it's worth having a look at how existing themes are defined, 
both at the C code level in Tk's C library, but also via the Tk scripts 
found in Tk's "library/ttk" directory or in third-party themes. Search for 
Ttk RegisterElementSpec in Tk's C library to see how elements are 
specified. 


18. Case Study: IDLE 
Modernization 


This chapter presents a case study of modernizing the appearance of a 
substantial Tk-based application. 


XL. This chapter is currently (May 2019) a work in progress. The code here is 
slowly finding its way into the Python source tree, but most is not there 
yet. You can find temporary snapshots on GitHub. 


IDLE (Integrated DeveLopment Environment) is the standard Python 
development environment that is bundled with every Python release. It 
consists of an interactive Python shell, editors with syntax highlighting, 
a debugger, etc. Its user interface is written in Tkinter. 
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Overview of IDLE user interface (on Linux). 


IDLE was never intended to be a replacement for more full-featured 
development environments. Because it is relatively simple and 
integrated, and because it is bundled with Python, it is popular for those 
learning (and teaching) the language. 

Originally created by Python BDFL Guido van Rossum in 1998, IDLE 
has been incrementally added to over the years by multiple other 


developers. But with limited development effort spent on it, it was 
showing its age, especially on platforms (e.g., macOS) infrequently 
used by those improving IDLE. 

A Python Central comparison of IDE's described IDLE this way: 


All those features are, in fact, present, but they do not really make 
an IDE. In fact, while IDLE offers some of the features you expect 
from an IDE, it does so without even being a satisfactory text 
editor. The interface is buggy and fails to take into account how 
Python works, especially in the interactive shell, the auto- 
completion is useless outside the standard library, and the editing 
functionality is so limited that no serious Python programmer — 
heck, no serious typist — could use it full-time. 


If you use an IDE, it should not be IDLE. 


With its buggy and dated user interface, IDLE was at some risk of being 
removed from the Python distribution altogether. Yet, because of the 
relative simplicity and it being bundled, there were a number of people, 
particularly those teaching Python, eager to see IDLE leap forward. 

IDLE was obviously a great candidate to be modernized, using 
newer Tk features like the themed widgets to help spur some redesign. 
But it was about more than just swapping widgets. Many improvements 
could be made just by changing how the "classic" widgets were being 
used, to better reflect a more modern design aesthetic. 


AXE. Because IDLE, which is an application, was a part of Python's standard 
library (i.e., 99% designed to be used by other code), there were many 
policies and procedures not really appropriate for an application that made 

changes difficult. Removing some of those roadblocks (see PEP 434) was a 
significant step required for the types of changes being discussed here. 


18.1. Project Goals 


As you can imagine, modernizing a large application like this, based on 
"classic" Tkinter, was not entirely straightforward. In this chapter, I'll 
walk through some of the user interface changes that were made and 
why. 

Everyone involved wanted to see IDLE look a lot better than it did, 
though nobody was under the illusion that it was going to turn into a 
stunning example of cutting-edge design. But something that fit in 
more, so that people could learn about Python without getting 
distracted by the clumsiness of their tools, seemed doable. 

The goal also wasn't to try to compete with Python IDE's more 
commonly used by professional programmers, such as PyCharm, 
WingIDE, PyDev, Komodo, etc. Though some more experienced 
Python developers did use IDLE, either sporadically or regularly, it 
primarily needed to appeal to newcomers to the language, and often 
those new to programming altogether. 

There has been no shortage of previous attempts to radically 
advance IDLE, resulting in a number of different forks that boasted all 
kinds of improvements. Many of them used other GUI toolkits or 
modules that weren't part of the standard library. It was important here 
to stay with Tkinter and the standard library because we wanted to 
ensure every improvement could, over time, make it into the official 
version that ships with Python, rather than becoming just another fork. 

As well, the hope was to make IDLE easier to contribute to. This 
suggested pruning down a substantial volume of code, removing some 
redundancies and inconsistencies, cleaning up some of the more 
complex pieces, simplifying interactions between system components, 
etc. There was also a substantial list of reported bugs that we hoped to 
make a dent in. 

While no less important, I'll largely defer discussion of the substantial 
issues surrounding software architecture, backward compatibility 
(including systems running Tk 8.4, pre-ttk, which received only a few 
selective improvements), etc. 

Throughout this chapter, you'll find links to individual issues in 
Python's issue tracking system, which often provide additional insight 


into various peoples’ thought processes around changes. 


XL. As you'll see, this chapter highlights many of the shortcomings of IDLE's 
user interface. This is done mainly for emphasis because many of the 
problems shown here are common to many applications and user 

interfaces. | have only the highest respect for the people who donated their limited 
time and resources to this open source project and had to consciously make 
tradeoffs between time, features, and user interface, all within the context of a 
decidedly non-trivial codebase. 


18.2. Menus 


The very first change that was made was to remove the archaic tearoff 
menus. The macOS version of Tk doesn't even support them, but they 
were still there on Windows and X11. See 
[bugs.python.org/issue13884]. 
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Tearoff menus on Windows and Linux. 


The change here was to add a "tearoff=0" option to the few places in 
the code where these menus were created. 

At least that was easy. 

There were also several bugs where items in the menu were not 
properly disabled when the feature was not available. This led to either 
menu items that did nothing (confusing for learners) or error dialogs 
that said little more than "you can't do that." 


18.3. Main Window 


One good thing about IDLE is that revolving around an editor and a 
shell, the majority of it really is a Tk text widget, and there was very little 
about its user interface that had to change. But even in the main 
window, which is mostly just a text widget, there were improvements to 
be had. 

The following images show the original version of IDLE's shell 
window, pre-modernization, just as someone would see when they first 
launched the program. 

Looking at them, what improvements would you make? 


& Python File Edit Shell Debug Options Window Help 


Python 3.4.3 Shell 


Python 3.4.3 (v3.4.3:9b73f£1c3e601, Feb 23 2015, 02:52:03) 
[Gcc 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin 
Type “copyright”, “credits” or “license()" for more information. 


Main IDLE window on macOS. 
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Main IDLE window on Windows. 
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Python 3.4.0 (default, Jun 19 2015, 14:20:21) 

[Gcc 4.8.2] on linux 
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Main IDLE window on Linux. 


Default Font 


The first change that was made had to do with the default font. IDLE 
hardcoded 10 point Courier and used that on all platforms. This didn't 
actually look too bad in Windows, was ok on Linux, but looked terrible 


on macOS; see [bugs.python.org/issue24745]. Sure this could be 
changed through a preferences dialog, but the defaults certainly didn't 
leave a good impression. 

While one option would simply be to write the code to pick a good 
font depending on which platform we're running on, instead the default 
was changed to use Tk's built-in tkFixedFont, which provides a better 
default on each platform. 

You can see the differences in the screenshots below. Notice how 
the new fonts seem to match better with system terminal windows that 
are shown. 


Python 3.4.3 (v3.4.3:9b73f1c3e601, Feb 23 2015, 02:52:03) 

(Gcc 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin 

Type “copyright”, "credits" or “license()" for more information. 
>> 


eee Python 3.4.3 Shell 

Python 3.4.3 (v3.4.3:9b73f1c3e601, Feb 23 2015, 02:52:03) 

[GCC 4.2.1 (Apple Inc. build 5666) Cdot 3)] on darwin 

Type "copyright", “credits" or "License()" for more information 
>>> 


IDLE main window using TkFixedFont (macOS). 


t & Python 3.4.3 Shell 
ee 6File Edit Shell Debug Options Window Help 
Python 3.4.3 (v3.4.3:9b73fic3e601, Feb 24 2015, 22:43:06) [MSC v.1600 
tel)] on win32 
Type "copyright", "credits" or "license()" for more information. 
>>> 
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IDLE main window using TkFixedFont (Windows). 
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File Edit Shell Debug Options Window Help 


Python 3.4.0 (default, Jun 19 2015, 14:20:21) 
[GCC 4.8.2] on Linux 
Type "copyright", "credits" or “license()" for more informatic 
>>> | 


IDLE main window using TkFixedFont (Linux). 


Speaking of preferences dialogs, if you want to change the font it often 
helps to know what the font actually is (using Font.actuai). Here's the 
new code from IDLE's preferences dialog that figures that out: 


if (family == 'TkFixedFont'): 
f = Font(name = 'TkFixedFont', exists = True, root = 


root) 

actualFont = Font.actual (f) 

family = actualFont['family'] 

Size = actualFont['size'] 

if size < 0: 

size = 10 # if font in pixels, ignore actual 

size 

bold = 1 if actualFont['weight']=='bold' else 0 


For the record, the fonts that Tk chose for TkFixedFont are Monaco 11 
on macOS, Courier New 10 on Windows, and DejaVu Sans Mono 10 
on Linux (Ubuntu 14 to be specific). 


Around the Text Widget 


There were a few other cosmetic things that just weren't right around 
the edge of the main window; see [bugs.python.org/issue24750]. Look 
back at the earlier screenshots of the IDLE main window. 

Notice there's a border around the text widget. It's most noticeable 
on macOS where it's a dark black, somewhat less so on Linux, and 
barely perceptible on Windows. This is the result of Tk's 
"highlightthickness" attribute, which is present when the text widget has 
the focus. 

If the text widget doesn't have the focus, such as when the window 
becomes inactive, the highlight goes away: 
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Mac OS X Windows Linux 
Status bar on inactive window. 


Notice how on the macOS screenshot, without the highlight, the status 
bar at the bottom of the window blends into the text widget. Not good. 


As you'll see from looking at other applications, the border around 
the text widget is no longer a common convention. So let's start by 
removing that, which is as easy as adding "highlightthickness=0" when 
we create the text widget. 

That still leaves us with the problem of the status bar blending into 
the editor. We changed the status bar to be a ttk.Frame widget, which 
has a background shading on all platforms. We also placed a 
ttk.Separator widget just above the status bar, to give us that clean 
separation. 

Each of the line and column indicators were labels, previously 
created with: 


label = Label(self, bd=1, relief=SUNKEN, anchor=W) 


This was replaced with a ttk.Label, to ensure it matched the frame. We 
also did away with the 1990's sunken "3d" look. 


label = ttk.Label (self) 


Last but not least, we can replace the original Tk scrollbar with the 
newer ttk.Scrollbar widget. 

The resulting changes to the main window are shown below. Despite 
these being fairly minor, often subtle changes, they go a long way 
towards IDLE's main window looking a lot cleaner, more modern, and 
"just fitting in" on all platforms. 
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IDLE's main window, with improvements (Windows). 
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IDLE's main window, with improvements (Linux). 


18.4. Preferences Dialog 


One visible piece that greatly needed improvement was _ the 
Preferences dialog. Again, here are screenshots on the three platforms: 


ee Settings 
Fonts/Tabs | Highlighting | Keys General | 


, Base Editor Font ~ Indentation Width 

Font Face : Python Standard: 4 Spaces! 
Monaco 4 

Monaco CY | ae 

Monotype Corsiva 2 4 6 8 10 12 14 16 


Size: 11 


AaBbCcDdEe 
FFGgHhIiJjK 


1234567898 
#:4-O{}0 


Ok Apply Cancel 


IDLE's Preferences window (macOS). 


Fonts/Tabs Highlighting | Keys | General | 


~ Base Editor Font 


Font Face: 


\Courier New Baltic 
‘Courier New CE 
‘Courier New CYR 
‘Courier New Greek 


Size: 10 — l Bold 


AaBbCcDdEe 
F£GgHnIidjK 
1234567890 
#:+=() {3 0) 


Indentation Width 
Python Standard: 4 Spaces! 
4 
| 
2 4 6 8 10121416 


ox] tor | cs 


IDLE's Preferences window (Windows). 


Settings 
Fonts/Tabs | Highlighting | Keys | General | 


- Base Editor Font —---—————-_ - Indentation Width 
Font Face : Python Standard: 4 Spaces! 
DejaVu Sans Mono : 4 
DejaVu Serif 
Dingbats 2 4 6 8 10121416 
Droid Arabic Naskh 
Droid Sans 


AaBbCcDdEe 
FfGgHhIiJjK 
1234567890 
#:+=(){}[] 


Ok | Apply | Cancel | 


IDLE's Preferences window (Linux). 


The other tabs allow you to modify individual colors for syntax 
highlighting, keystrokes assigned to particular operations, and a few 
other miscellaneous things. 

While there was some debate as to the need for this level of 
configuration on what was primarily a learning environment, it seemed 
reasonable to at least make what was there look and work better before 
considering any more radical surgery; see 
[bugs.python.org/issue24810]. 

Among other things, the Preferences dialog was changed from 
modal (which, amusingly enough, didn't quite work on macOS, allowing 
multiple copies to be created) to modeless, though | won't go further 
into that at this point; see [bugs.python.org/issue24760]. 


Tabs 


The first issue to address was the tabs used to switch between the four 
different preference panes. The original used a custom "megawidget", 
as classic Tk doesn't have its own widget. While the Windows and 
Linux ones don't look too bad, on recent versions of macOS, there is a 
built-in tab widget that looks quite different. 


Q It's actually more common in macOS applications now to use something 
similar to a toolbar (row of icons with labels along the top or side) to switch 
between preference panes, though some programs do still use tabs. Tabs 

are very common on Windows and Linux. 


The code was modified to use the ttk.Notebook widget, which not only 
looks better on each platform but allows us to jettison a lot of code for 
managing tabs ourselves. 


Updating Widgets 


The next obvious step was upgrading the "classic" widgets to their 
themed counterparts. On this screen, that included the buttons, labels, 
frames, checkbox, scrollbar, etc. There were a few others on some of 
the other panes. Generally, this was a straightforward process, often 
involving removing widget options that were no longer needed or 
supported by the themed widgets. 

Sometimes choosing a different widget made more sense. In this 
screen, the option menu used for font size was better replaced by a 
combobox. Similarly, the scale widget is not commonly seen in today's 
user interfaces and was replaced with the more familiar (and compact) 
spinbox widget. 

There were also various non-standard ways of using certain widgets 
or specifying certain types of data. These were generally modified to 
use more familiar paradigms. There were a number of general issues 
discussed relating to the design of these dialogs, see, e.g., 
[bugs.python.org/issue24776], and 
[bugs.python.org/issue24782]. 


Layout 


While this dialog is a bad example, just given the space imbalance 
between the left and right halves, a lot of time was spent in general 
looking at widget spacing and alignment in dialog boxes. 

The general approach was to find similar examples in other 
applications and use those as a guide. Where are the buttons located? 
How are multiple fields of a dialog organized? Where are labels relative 
to the widget they're labeling? Are they left- or right-aligned, capitalized, 
do they have a trailing colon? These are the sorts of questions to think 
about. 


Q A great starting point is converting from using the old pack geometry 
manager to gria. Because of the way it works, pack-based layouts tend to 
have weird and inconsistent alignment and spacing, especially if they've 

been modified over time. Using gria will increase maintainability, both because it 

uses a more familiar mental model and because it's not dependent on the order in 
which widgets are inserted. 


It's likely impossible to come up with one layout that looks fantastic on 
all platforms, but often you can come up with one (possibly with a 
couple platform-specific tweaks in the code) that looks decent. 

A revised version of the dialog, incorporating many of the techniques 
here, is shown below. 


Extensions 


Monaco CY 
Monotype Corsiva 


FfGgHhlidjK 
1234567890 
#:+=000 


Font Size: 11 a | Bold 
Indent: 4 9 < Python Standard: 4 Spaces! 


OK Apply 


IDLE Preferences, revised version (macOS). 


Piece oe 
Preferences 


Fonts/Tabs | Themes 


Cancel 


Courier New Baltic 
Courier New CE 
Courier New CYR AaBbCcDdEe 
Courier New Greek FFGgHhliJjK 
Courier New TUR 1234567890 
DFKai-SB #+=000 
DaunPenh 
David 
DilleniaUPC 
DokChampa 


Dotum 
DotumChe 
Ebrima 


FontSize:: 10 + [| Bold 


Indent: 4 > Python Standard: 4 Spaces! 


Cone 


IDLE Preferences, revised version (Windows). 


Preferences 


Fonts/Tabs | Themes | Keys | General Extensions | 


DejaVu Sans Mono 
DejaVu Serif 
Dingbats 

Droid Arabic Naskh AaBbCcDdEe 
Droid Sans FFGgHhIijjK 
Droid Sans Armenian 1234567890 
Droid Sans Ethiopic #:4+=0{}0) 
Droid Sans Fallback 
Droid Sans Georgian 
Droid Sans Hebrew 
Droid Sans Japanese 
Droid Sans Mono 
Droid Sans Thai 


Font Size: |10 | Bold 


¥!) 


Indent: |4 — Python Standard: 4 Spaces! 


OK Apply Cancel 


IDLE Preferences, revised version (Linux). 


Another Example 


The screenshot below shows a before and after of the IDLE 
Preferences pane, which controls syntax coloring; see 
[bugs.python.org/issue24781]. 


Lg Settings 
Fonts/Tabs | Highlighting | Keys | General | 


; Custom Highlighting ———————__ - Highlighting Theme 
Select: 


Choose Colour for: aos 
© a Built-in Theme 


( Foreground © Background IDLE Classic amt 
ERE RSL ITER ae IDLE Classic Copy —! 


def func(param): 

"""string™"" Delete Custom Theme | 
var0O = 'string' 
vari = 


var2 
var3 = list (None) 


(EEEEEY cursor | 


shell stdout stderr 


Save as New Custom Theme | 
Ok | Apply | Cancel | 


IDLE Themes pane, before (Windows). 


G ? Preferences 


|Fonts/Tabs Themes Keys | General] Extensions| 


IDLE Classic 

IDLE Classic Copy 

IDLE New 
r""string™" 
varo *string' 
vari 
var2 
var3 list (Non 


| 
ESEBERY cursor | 


shell stdout stderr 


Python Comments 
Foreground: @ 


Background: | | 


| | Apply | Cancel 


IDLE Themes pane, after (Windows). 


Again, substituting widgets and using more familiar conventions is one 
piece of this. | think the bigger changes have to do with thinking about 
things from the users' perspective. Particularly as a beginner tool, if 
you're in here at all, it's probably to switch themes, not tweak colors, 
which is more prominent in the new version. It also does away with an 
arbitrary distinction between "built-in" and "custom" themes. 

| think the new version is a big improvement, though as of this writing 
| have yet to convince some people of this. This being open source, 
we'll see what happens! 


18.5. Other Dialogs 


There are multiple other dialog boxes in IDLE; we'll consider a couple 
more examples here. 


Find Dialog 


Ax Planning on doing some more changes on these, likely combining Find 
and Replace into a single dialog. 


One of the find/search dialogs is shown below, again with before and 
after on the three platforms; see [bugs.python.org/issue23218]. 


eae Search Dialog 


Find: | ¥ | close 


Options Regular expression Match case | Whole word & Wrap around Find Next, 


Direction | ) Up © Down 
eee Search Dialog 


Find: | 


Options: Regular expression | Matchcase | Whole word © Wrap around 
Direction: | ) Up © Down 


IDLE Find dialog, before and after (macOS). 


Options [~ Regular expression [ Matchcase [ Wholeword [¥ Wrap around 


Direction ( Up @ Down 


Find: 


Options: Regular expression |_| Match case || | Whole word Wrap around 


Direction: () Up @ Down 


IDLE Find dialog, before and after (Windows). 


Search Dialog 


Options {[ Regular expression [ Match case | Whole word |¥ Wrap around Find Next 


Direction © Up ™ Down 


Search Dialog 


Options: | Regular expression | Match case’ Whole word X Wrap around 


Direction: ( Up ‘* Down 


as 


IDLE Find dialog, before and after (Linux). 


The first step was upgrading the widgets to use the equivalent themed 
widgets. The effect of this is most obvious with the buttons (being 
consistent with the capitalization doesn't hurt either). 

Speaking of buttons, notice that in the new version, the buttons are 
on the right on Windows (where they were on all before), but at the 
bottom for macOS and Linux. On examining multiple different 
applications, our target users would likely have encountered on each 
platform, we found these locations were common. With only a few lines 


of extra code needed to special case for this layout difference, it made 
sense to handle things this way. 

Other aspects of the layout were also improved. Looking at the 
original dialogs (especially how the buttons don't quite line up with other 
widgets), | originally thought it was created with pack, and expected to 
convert it to grid. Interestingly, it was already using gria. Why then the 
unaligned widgets, a hallmark of pack-based layouts? 

This turned out to be a result of using many nested frames. For 
example, the buttons were placed into their own frame, and then that 
placed into the rest of the window. Because of that, the individual 
buttons couldn't be aligned with widgets in the rest of the user interface. 

Nested frames were required when using pack, but often with gria it 
is better to avoid them except in exceptional circumstances. That 
allows you to make different parts of the user interface line up (at the 
expense of dealing with a lot of columnspan/rowspan tweaking). 

A more substantial reorganization would have likely removed the 
nested frames, but particularly with adjusting the buttons, this relatively 
simple layout could be made to work with just a few tweaks. 


Q You'll notice a lot of older Tkinter user interfaces have the problem here of 
their contents running to the edge of the windows, which often doesn't 
look right. I've gotten into the habit of placing a ttk.Frame directly inside 

each toplevel, with some additional padding, and then placing the rest of the user 

interface inside that. 


Like Preferences, the Find dialogs were also modal, which meant you 
had to dismiss them before doing any editing of your file, though at 
least they did remember the previous settings when you reopened 
them. These were eventually changed to be regular modeless 
windows. 


About Dialog 


Speaking of modal dialogs, the About box was also originally modal. 
Not only that, getting more information (e.g., the IDLE README file) 
resulted in launching another modal dialog, which needed to be 
dismissed to go back to the first modal dialog, which needed... etc. 


IDLE 


Python's Integrated DeveLopment Environment 


email: idle-dev@python.org 
https://docs.python.org/3.4/library/idle.html 


Python version: 3.4.3 Tk version: 8.5.18 


Close 


@0@ About - Readme 


IDLE is Python's Tkinter-based Integrated DeveLopment Environment. 


IDLE emphasizes a lightweight, clean design with a simple user interface. 
Although it is suitable for beginners, even advanced users will find that 
IDLE has everything they really need to develop pure Python code. 


IDLE features a multi-window text editor with multiple undo, Python colorizing, 
and many other capabilities, e.g. smart indent, call tips, and autocompletion. 


The editor has comprehensive search functions, including searching through 
multiple files. Class browsers and path browsers provide fast access to 
code objects from a top level viewpoint without dealing with code folding. 


There is a Python Shell window which features colorizing and command recall. 


IDLE executes Python code in a separate process, which is restarted for each 
Run CFS) initiated from an editor window. The environment can also be 
restarted from the Shell window without restarting IDLE. 


This enhancement has often been requested, and is now finally available. The 
magic "reload/import *" incantations are no longer required when editing and 
testing a module two or three steps down the import chain. 


SP paeabtai Firewall software may warn about the connection IDLE makes to its 


rubmmne nnn ela Ahi nnwiibawtlea Jabawnnd Dennhacl J wbaanlanan Thi enwnnndian 


Close 


IDLE's doubly-modal About dialog (macOS). 


Making the dialog non-modal was the first priority. Second, the nested 
dialogs were eliminated using a progressive disclosure technique. The 
dialog when launched is fairly sparse but contains a ‘More...’ "link." 
When clicked, it expands the window to show one of the documentation 
files, with an option to switch to any of the others. 

The ‘More...’ "link" is effectively playing the role of a button, but 
taking advantage of everyone's familiarity with web browsers to provide 
a visually simpler alternative. As far as implementation, we use a 
(classic, non-themed) label widget, colored blue, and attach a mouse 
click binding to it. 


One thing you can do to help convey that the link is clickable is to change 

the cursor when the mouse is over it (via the "cursor" option found on 

many widgets). On macOS, choose the platform-specific "pointinghand" 
cursor, on Windows and Linux choose the "hand2" cursor, which actually gets 
mapped to something more appropriate on those platforms. 


About IDLE 


IDLE is Python's Tkinter-based Integrated DeveLopment Environment. 


IDLE emphasizes a lightweight, clean design with a simple user interface. 
Although it is suitable for beginners, even advanced users will find that 
IDLE has everything they really need to develop pure Python code. 


IDLE features a multi-window text editor with multiple undo, Python colorizing, 
and many other capabilities, e.g. smart indent, call tips, and autocompletion. 


The editor has comprehensive search functions, including searching through 
multiple files. Class browsers and path browsers provide fast access to 
code objects from a top level viewpoint without dealing with code folding. 


There is a Python Shell window which features colorizing and command recall. 


Revised About dialog (macOS). 


Online Help 


IDLE also had a (needless to say, modal) help dialog which displayed 
information on using the program. This displayed a plain text help file 
that looked similar to the 'About - Readme’ window above. 


At the same time, like the rest of Python, there was reference 
documentation, created as "restructured text" which can then be 
formatted using a tool called Sphinx into HTML, text, etc. 

The documentation in IDLE's help dialog was based on a separate, 
but similar plain text file. Keeping the two in sync was a problem. They 
were separate because Sphinx's plain text rendering didn't look all that 
good, and all the extra navigation, etc. in the HTML rendering wouldn't 
be needed for online help, and then there's the hassle of opening a web 
browser, etc.; see [bugs.python.org/issue16893]. 

Tk's text widget is smart enough to handle the very basic formatting 
used in IDLE's documentation, and Python includes an HTML parser in 
its standard library. Putting the two together made displaying a 
simplified version of the HTML reference documentation easy. 


@eae IDLE Help 
Toc fj IDLE 


IDLE is the Python IDE built with the tkinter GUI toolkit. 
IDLE has the following features: 


* coded in 100% pure Python, using the tkinter GUI toolkit 

* cross-platform: works mostly the same on Windows, Unix, and Mac OS X 

* Python shell window (interactive interpreter) with colorizing of code input, output, and error 
messages 

* multi-window text editor with multiple undo, Python colorizing, smart indent, call tips, auto 
completion, and other features 

* search within any window, replace within editor windows, and search through multiple files 
(grep) 

* debugger with persistent breakpoints, stepping, and viewing of global and local namespaces 
* configuration, browsers, and other dialogs 


1. Menus 


IDLE has two main window types, the Shell window and the Editor window. It is possible to have 
multiple editor windows simultaneously. Output windows, such as used for Edit / Find in Files, are a 
Sublvoe of edit window, They cumecth. pave the some too meni ss Soitor windows but a ditersat 


Online help using text widget (macOS). 


AX. It's easy to get carried away here. Back in the mid-1990s, a tiny HTML 
parser_in_Tcl spawned a slew of "web browser in a text widget" 
adventures, first in Tcl and then in other languages, e.g., Python's Grail. 

Trying to keep up with everything that large teams of developers are putting into 

real web browsers is a fool's errand. Yet, for very limited and constrained subsets 
of HTML (as might be found in online help), it's an entirely reasonable approach. 


Query Dialogs 


Still with the modal dialog theme, IDLE used the "simpledialog" 
package, which is distributed as part of Tkinter to request certain small 
pieces of information from users via modal dialogs. An example is the 
"Goto line..." command. This, along with an example of the alert that is 
presented if you type in something invalid is shown below. 


@@e@ Goto ®@ Goto 


Go to line number: Not an integer. 


foo| a Please try again 


Cancel 


Goto line dialog and error handling (macOS). 


The alert-on-dialog isn't quite as bad as the dialog-on-dialog pattern we 
saw before. But these dialogs could certainly stand to be cosmetically 
updated, and a few other tweaks made. For example, while they 
correctly interpreted hitting the Return or Escape keys as synonymous 
with pressing OK or Cancel, they didn't also allow for the alternate 
macOS conventions (Enter key on the numeric keypad and Command- 
period); see [bugs.python.org/issue24812]. There were some other 
customizations that would have been nice to have, e.g. changing the 
name of the OK button, that simpledialog didn't support. 

Regarding the error handling, things were, in some cases, handled 
worse. For example, there is a command to open an editor window 
containing the source of a module from Python's stdlib. See what 
happens if you make a typo. 


@o0e@ Module 


Enter the name of a Python module 
to search on sys.path and open: 


COKE Cancel 


om) Python 3.4.3 Shell 


Python 3.4. 
[GCC 4.2.1 £\ module not found 
Type "copyr 


Open module dialog with error (macOS). 


Because the dialog doesn't know if the module name is correct, 
validation isn't done until after the dialog is dismissed. So the error alert 
gets attached to another window. To try again, you have to dismiss that, 
use the menu to reopen the dialog, and try again (from scratch). 

There were a couple of places in the code where more validation in 
the dialog was really necessary. Because the "simpledialog" code was 
part of Tkinter and wasn't readily extensible in the ways needed, 
developers had to resort to "inheritance by text editor" (i.e., copy the 
entire simpledialog code and modify the copy). Twice, separately. 

Since the appearance needed to be updated anyway, we 
generalized things and ignored what was in Tkinter's simpledialog 
module altogether. Instead, a single general-purpose replacement was 
created that could be used throughout IDLE (and still resulted in less 
code). 


Goto 


Go to line number: 


foo| 


Must be an integer 


New query dialog (macOS). 


Besides the updated widgets and alignment, notice how error 
messages from invalid input are now shown in the dialog itself (a 
technique seen frequently in web applications), rather than a separate 
alert. For macOS, we also made sure to add key bindings for the 
numeric keypad Enter key and Command-period, and also made sure 
the window looked like a modal dialog is supposed to via this little gem: 


self.tk.call('::tk::unsupported::MacWindowStyle', 'style', 


self. w, 


"moveableModal', '') 


As far as validation, the query dialog was structured to accept a 
validation callback, which could then handle arbitrary criteria. For 
example, here is the validation code used when people enter the name 
of a new theme. It makes sure it fits certain syntactical requirements 
and also hasn't been already used. 


def newtheme (self): 
def validate theme(s): 
if not s: 
raise ValueError('Cannot be blank") 
if len(s) > 30: 
raise ValueError('Cannot be longer than 30 


characters') 
if s4in séltvall theme-names()s 
raise ValueError('Name already used') 
new theme = querydialog.askstring(parent=self, prompt='...', 
title='Create New Theme', 
validatecmd=validate theme) 
if new_theme is not None: 


A generic ‘integer’ validation callback, with an optional minimum and 
maximum, was added as part of the query dialog module for dialogs 
like the 'Goto line...’ dialog. 


Dialog Placement 


Several dialogs, including alerts, file save, etc. were appearing in the 
middle of the screen, rather than close to the window that they were 


associated with; see [bugs.python.org/issue25173]. 

Choosing the right window as the parent of the dialog is important. It 
ensures the dialog window appears near that window. On macOS, 
these dialogs are often attached to the title bar of the parent window 
(see the error alerts in the previous section). 


The front ends to these dialogs in Tkinter support both a master and a 

parent. While most of the time, "master" and "parent" are used 

interchangeably in Tkinter, that's not the case here. If you provide only the 
master, the dialog won't be attached to that window (but the dialog still needs an 
existing window to create the dialog, which is why the master parameter is there). 
If the dialog is associated with another window, be sure to use the parent 
parameter. 


18.6. Window Integration 


Multiple people had hoped to make it possible to have everything 
displayed in a single window, to avoid the window management hassles 
that can sometimes trip up people, see, e€.g., 
[bugs.python.org/issue9262], [bugs.python.org/issue24826], and 


[bugs.python.org/issue24818]. 
Below is an early, partially-functional mockup of some of the things 


we wanted to be able to accomplish. 


@ © @  uipreferences.py - /Users/roseman/vboxshare/cpython/Lib/idlelib/uipreferences.py (3.6.0a0) 


ulpreferences.py uitabs.py querydialog.py 7 
""""When a theme, color or the active element changes, update the 
colors in the UI, both the sample and also the color wells, to match 
the new state.""" 
theme = self.theme_v.get() 
for element in self.elements: 

elt = self.elements[element][@] 
fg = self.current_color(self.theme_v.get(), element, ‘fg') 
bg = self.current_color(self.theme_v.get(), element, ‘bg') 
if elt == ‘cursor’: 

bg = idleConf.GetHighlight(theme, ‘normal’, fgBg='bg') 
self.sample.tag_config(elt, background=bg, foreground=fg) 
if element == self.element_v.get(): 

self. foregroundWell.configure(background=fg) 


| ea a aah 


def all_theme_names(self): 
themelist = self.default_themes[:] 
userlist = idleConf.GetSectionList('user', ‘highliqht') 


> EG & EH 


Program stopped by exception. 
Go Step Over Out Stop 9 Pp y - Vv Locals 
bg ‘Hf fff 
_init_. self.rebuild_themes_list) ane ee ee ee 
rebuild_themes list self.theme_changed() elt ee ' 
theme_changed() self.update_colors() fg #770000 
update _colors() x=5/0 self <__main__.ThemesPane 
ZeroDivisionError: division by zero Lagat oane ‘IDLE Classic’ 
Type "copyright", "credits" or "lLicense()" for more information. 
>>> 
(DEBUG ON] 
| >>> 
=ee== RUN /Users/roseman/vboxshare/cpython/Lib/idlelib/uipreferences.py ===== 
Ln: 478 Col:8 


Early mockup of window integration (macOS). 


XL. At this point, almost everything here has been completed, and it ended up loo 
— almost identical to the original mockup. See, once in a while, it happens! 


Tabbed Editor 


Even beginner programmers have to juggle multiple different source 
files. If each gets its own window, as was the case originally in IDLE, 
things can get messy and/or lost pretty quickly. Using tabs to organize 
multiple files in a single window is a familiar, effective solution. 


When architecting your application, don't build large components as 

subclasses of Toplevel, or assume they'll be the only thing in the window 

in the future. Getting around that assumption in the code took a large 
amount of work. If components are instead built as frames, they can be more 
easily inserted into a toplevel, a paned window, a tabbed notebook, another frame, 
etc. 


Luckily, we can rely on the ttk.Notebook widget to provide the tabbed 
user inteface, just like we did in Preferences. 

Or maybe not. 

Unfortunately, the ttk.Notebook widget (and the underlying platform 
widgets it uses) only really support displaying and switching between a 
small, fixed number of tabs. There's nothing built-in to support adding 
or closing tabs from the user interface, which we definitely need here. 
And as every programmer knows, it is more than possible to need a 
large number of tabs. 

As you've seen in different editors and word processors, everyone 
does things slightly differently. We did our own custom tab widget 
(sigh...) for IDLE. The design borrowed heavily from the TextMate editor 
on macOS. It allows creating new tabs, closing old ones, dragging to 
rearrange the order, tooltips on each tab, indicating if the contained file 
needed saving, etc. When the number of tabs grows too large to 
comfortably display, the remainder are accessible via a popup menu on 
the last visible tab. 


AX. The tabbed widget implementation relies on a single Tkinter canvas to 
display the row of tabs and handle all interaction. The actual switching of 
window content is handled completely outside of the widget, with a simple 

callback mechanism used to coordinate everything. 


Debugger 


The design of the original debugger, along with having its own set of 


flaws (see [bugs.python.org/issue17942]), was too tall to be integrated 
like we wanted to do. 


eee Debug Control 

Stack Source 
Locals |_| Globals 
Untitled.py:1: <module>() 


Go Step Over Out Quit 


"bdb'.run(, line 431: exec(cmd, globals, locals) 
'_main__'.<module>(), line 1: import random 


Locals 


__builtins_. <module 'builtins' (built-in)> 


__doc__ None 

__file__ '/Users/roseman/desktop/Untitlec 
_loader__ <class '_frozen_importlib.Builtinin 
__name__ *__main_' 


__package__ None 


__spec__ None 


Original IDLE debugger (macOS). 


The user interface was substantially revised, with a layout that would 
work both in a standalone window and when integrated. The new 
version uses a paned window to separate the controls and stack on the 
left from the variable display on the right. Both the stack and variable 
display are implemented using tree view widgets. This also provides a 
great deal of control when it comes to how much space each element 
will use. 


eee Debug Control 
> & GF Gi B® 


Go Step Over Out Stop Options ¥ Locals 
Untitled.py:1: <module>() __builtins__ <module 'builtins' (built- 
_ doc__ None 
Idb.run exec(cmd, globals, local file ‘/Users/roseman/deskto 
| > <module> import random _loader__ <class '_frozen_importlit 
__name__ ‘_main_' 
__package. None 


__spec_. None 


~~ 


New IDLE debugger (macOS). 


Integrated Shell and Debugger 


To achieve the integration of the shell and the debugger with the tabbed 
editor, another paned window was used. Additional controls will be 
added to show/hide the panes as the implementation progresses. 

The embedded shell is interesting too. Recall that IDLE normally has 
a single Python shell window running another Python process; when 
modules in an editor are "run," they do so via that shell. It's nice to have 
that big shell available, and we don't necessarily want to start up a 
separate shell in the editor. 

New in Tk 8.5, the Text widget actually supports the ability to create 
"peers," which are separate widgets, but they share the same text 
backend. That means when something changes in one, it changes in 
the other. It's a seamless way to solve our problem here. 


18.7. Workarounds, Hacks, and More 


This being a chapter on actual experiences modernizing a real 
application, it would be a lie to say that the underlying user interface 
toolkit (Tk and the Tkinter wrapper) always worked exactly as it should. 
Like IDLE, Tkinter and Tcl/Tk are the results of incredible volunteer 
efforts. That being said... 


& Tk and Tkinter have some bugs and rough edges. | know you're shocked. 


In this section, I'll try to catalog just a few of the particular 
"gotchas" that we ran into, as well as provide some little tips that don't 
necessarily fit elsewhere but help provide a bit more polish to the user 
interface. 


Tool Tips 


¢ tool tips broken on macOS; 
see [bugs.python.org/issue24570] 


* MacWindowStyle help for tooltips, VS. wm  overrideredirect 
elsewhere 


Context Menus 


e bogus text widget bindings interfere with popup clicks; 
see [bugs.python.org/issue24801] 


e two different popup click bindings needed on macOS; 
[bugs.python.org/issue24801] 


Peer Text Widgets 


e broken peer text widget API in Tkinter; 
see [bugs.python.org/issue17945] 


Modal Windows 


